# Topolo Docs full corpus (public) This is the human-authored Topolo documentation corpus for retrieval by agents and language models. Runtime action schemas and credential-scoped permissions remain authoritative at execution time. Manifest: https://docs.topolo.app/manifest.json Machine index: https://docs.topolo.app/machine/index.json # System registry - Socialize (socialize): Social publishing and campaign tooling with brand-scoped workflows, Nexus-authoritative connected-provider state, and local reference-only target selection. Repositories: apps/TopoloSocialize. - Topolo Admin (topolo-admin): Administrative interface for centralized auth, org management, org-scoped role and user-access management, app-centric service assignment, support-facing personal and service-local identity visibility, household-connection context, org billing preview, service controls, audit surfaces, and cross-app handoff into other internal operator tools. Repositories: apps/TopoloAdmin. - Agent (topolo-agent): Agent and automation workspace for threads, workflows, approvals, outbound campaign readiness and suppression, operator execution, and reusable source-backed person profiles. Repositories: apps/TopoloAgent. - Topolo Auth (topolo-auth): Central identity, personal workspace and household-membership authority, organization-context selection authority for org-scoped service entry, canonical app-workspace ownership and same-organization member-access policy authority, per-application permission partition and organization-scoped role authority, bounded exact application authorization and organization-entitlement authority, service registry, role-scoped default platform-service access policy, service lifecycle/accessibility and surface-classification authority, API key authority, app-switcher preference and platform shell-theme authority, browser/headless Auth SDK owner, Flutter Auth SDK owner, principal metadata source for service-local and agent identities, billable org-seat authority, and AI workforce credential/token authority across the platform. Broad application and action discovery is owned and paged by Topolo Developers. Repositories: topolo-platform/core/TopoloAuth, topolo-platform/packages/topolo-auth-client, topolo-platform/packages/topolo-auth-middleware, topolo-platform/core/TopoloAuth/packages/topolo_auth_flutter. - Blog (topolo-blog): Governed editorial workspace for drafts, immutable revisions, publication scheduling, media, SEO metadata, and public headless article delivery. Repositories: apps/TopoloBlog. - Topolo Brand (topolo-brand): Canonical versioned brand identity, assets, voice, claims, CTAs, and validation for Topolo applications. Repositories: apps/TopoloBrand. - Improve Topolo (topolo-bugfix): Shared contribution and triage surface for Topolo issues, ideas, and product improvements, backed by BugFix AI analysis and pull-request automation. Repositories: system-apps/TopoloBugFix, system-apps/TopoloBugFixRunner. - Bytes (topolo-bytes): Media and asset management surface for uploads, organization, review, and sharing. Repositories: apps/TopoloBytes. - Calendar (topolo-calendar): Cloudflare-native scheduling and bookings application with public booking pages, availability, invitations, recurrence, and Google/Microsoft/CalDAV free/busy sync. Repositories: apps/TopoloCalendar. - Chat (topolo-chat): Cloudflare-native collaboration application for channels, DMs, cross-app Chat widget, meetings, guests, and remote assist. Repositories: apps/TopoloChat. - Topolo CLI (topolo-cli): Node-based command-line client for Topolo operators and automation agents, built on top of the shared Topolo SDK. Repositories: topolo-platform/packages/topolo-cli. - TopoloCommerce (topolo-commerce): TopoloCommerce is the multi-vertical commerce application for Topolo organizations that operate one or many venues, built on a shared commerce core with optional vertical packs enabled per venue. The workspace ships a Worker API that owns org and venue settings, module resolution, catalog state, guest sessions, carts, orders, service requests, and device metadata; an authenticated ops app for org and chain operations; a tablet-first station app for kitchen, POS, bar, and expo execution; and a public guest runtime. A local Venue Edge service acts as the venue authority for low-latency execution and syncs edge-authored operational records back to the cloud. Repositories: apps/TopoloCommerce. - TopoloCRM (topolo-crm): CRM workflows, records, and SDR inbox/control-plane services exposed through the platform auth layer. Repositories: apps/TopoloCRM. - Topolo Design (topolo-design): Standalone brand-governed design workspace for static media and short animated creative exports. Repositories: apps/TopoloDesign. - Topolo Developers (topolo-developers): Standalone developer control plane with a public signup entrypoint, per-application manifest and machine-action partitions, notification-contract publication and discovery, credential-scoped discovery for SDK/CLI/MCP, the Developers-owned Topolo app store read model, bounded registry reconcile, and the authenticated workspace-backed console where publishers and internal operators manage applications, artifacts, submissions, visibility, commerce, pricing, and payout readiness. Repositories: apps/TopoloDevelopers. - Topolo Device Platform (topolo-device-platform): Topolo platform-owned TopoloFeed delivery, analytics, Android playback, and device-side app-catalog consumption surfaces. Repositories: apps/TopoloFeed. - TopoloDocs (topolo-docs): Canonical documentation, system registry, machine-readable platform evidence, and docs validation surface for the Topolo Platform. Repositories: system-apps/TopoloDocs. - Topolo Forecast (topolo-forecast): Cash-flow and P&L forecasting product. Repositories: apps/TopoloForecast. - Topolo MCP (topolo-mcp): Model Context Protocol server that exposes scope-gated Topolo SDK tools to local agent hosts. Repositories: topolo-platform/packages/topolo-mcp. - TopoloMDM (topolo-mdm): MDM platform cluster spanning a device API, tenant realtime hub, operator console, Android DPC, and mobile scaffold. Repositories: apps/TopoloMDM. - TopoloMessages (topolo-messages): Channel-agnostic business messaging: owns conversations, contacts, campaigns, templates, automations, and the outbound job pipeline. External providers (WhatsApp among them) are connectable channels behind it, not the product; provider state is read from the provider, not treated as the source of truth. Repositories: apps/TopoloMessages. - Topolo Nexus (topolo-nexus): Gateway and usage-management layer for standardized AI, email, payment, generic application usage events, and authoritative provider-neutral connection identity, lifecycle, profiles, and credentials across Topolo. Repositories: topolo-platform/services/TopoloNexus. - TopoloOne (topolo-one): Unified personal and organization live workspace, personal-profile family management, authenticated app catalog, worker-backed pricing, owner-linked subscription billing, content, growth, and developer-acquisition surfaces for TopoloOne. Repositories: apps/TopoloOne. - TopoloP2P (topolo-p2p): Cross-organization capability network for human and agent business actions, approvals, immutable micro-ledgering, and TopoloPay-managed settlement. Repositories: system-apps/TopoloP2P. - Topolo Pay (topolo-pay): Payment worker handling orders, webhooks, admin APIs, and static-asset-backed application behavior. Repositories: apps/TopoloPay. - Topolo Platform (topolo-platform): Shared platform concepts spanning multi-context identity, zero-to-many org and household memberships, entitlements, owner-scoped billing boundaries, AI workforce principals, API keys, service registration, deployment, and observability. Repositories: topolo-platform/core/TopoloAuth, topolo-platform/core/TopoloCloudControl, system-apps/TopoloDocs, topolo-platform/services/TopoloLocalize, topolo-platform/packages/topolo-ui-kit. - Topolo Quro (topolo-quro): QR creation, redirect, and scan-tracking application with modern and legacy UI surfaces. Repositories: apps/TopoloQuro. - Topolo Roadmapper (topolo-roadmapper): Roadmap and project management application in the Topolo portfolio with AI onboarding, scoped project-chat planning sessions, hierarchy-wide guest sharing and guest edit auditability, and narrative presentation delivery. Repositories: apps/TopoloRoadmapper. - Social Studio (topolo-social-studio): Hybrid desktop and web production surface for social planning, generation, review, and export. This is the only live Studio-branded application in the suite. Repositories: apps/TopoloSocialStudio. - Topolo Status (topolo-status): Public Topolo status page and monitoring cron for production surface health. Repositories: system-apps/TopoloStatus. - Topolo Support (topolo-support): Tenant-scoped support platform for Topolo internal operations and customer-organization ticket workflows, with support-owned workflow persistence kept outside Topolo Auth. Repositories: apps/TopoloSupport. - TopoloWeb (topolo-web): Chat-first website platform with a signed-in studio, Nexus-backed agent planning, Worker control plane, Astro runtime, publish snapshots, domains, forms, assets, and launch QA. Repositories: apps/TopoloWeb. # Documentation ## Topolo Auth API Canonical URL: https://docs.topolo.app/reference/api/topolo-auth Curated reference overlay for the Topolo Auth service where platform semantics matter more than raw route listing. ## Important route families - authentication and session validation - browser SSO authorize, exchange-code completion, and bearer-backed handoff-code creation - organization and service registry queries - credential and application-scoped permission projection for the Developers action catalog - service API key scopes - service API key bindable resources - API key create, list, revoke, and validation flows - developer-workspace signup and approved-app registration handoff for Topolo Developers - internal billing-plane provisioning: passwordless workspace creation from a completed checkout and live workspace-URL availability lookup - internal service export and catalog seeding routes used by Docs, SDK, and registry repair flows - bulk app availability and app-id mapping routes used by app catalog, launcher, Seed, and entitlement repair paths - permission-scoped portable user and organization export plus separately confirmed permanent deletion ## Why this page exists Topolo Auth exposes platform semantics that are broader than a raw endpoint index. Use this page for behavioral guidance, then use generated reference where a formal spec exists for a downstream service. ## Operational contract - resolved user permissions are emitted in the canonical `appId.resource:action` form - `GET /api/users/:userId/permissions` returns the evaluated permission payload for authenticated inspection, including `effectivePermissions`, effective permission entries, and source breakdowns for org service access, role bundles, and user overrides - Auth user payloads may now also expose explicit external-identity context through `principalType`, `principalServices`, and `launcherEligible`, so downstream control-plane surfaces do not need to infer service-local users solely from missing organization membership - service scope metadata for API keys is served from Auth D1 - service catalog responses include `surface_kind`, `surface_group`, and `launchable` so clients can separate human applications from APIs, runtimes, and internal support services - scoped service catalog responses include the stable `app_id` projection when Auth can map a service row to a Developers/catalog application record; consumers must treat Auth app ids and Developers `dapp_*` ids as different identifiers - service permission definitions are isolated by application; callers and Topolo Developers request bounded app-scoped projections rather than reading a global permission table - default role bundles for each registered first-party service are served from Auth D1 alongside the service permission and API key scope catalogs - resource-binding catalogs for supported services are also served from Auth D1 - clients should not hardcode service scope lists or fetch bindable resources directly from application UIs - browser clients should use `topolo-platform/packages/topolo-auth-client` and service backends should use `topolo-platform/packages/topolo-auth-middleware` for login, refresh, token validation, and permission matching semantics - service backends must not authorize protected routes from locally decoded JWT claims alone; successful bearer-token authorization requires Auth `/validate`, and Auth validation outage should fail closed - app-switcher service-listing routes honor an explicit `Authorization: Bearer …` token before falling back to auth cookies, so stale browser cookies do not override the caller's current in-memory session - app-switcher launches use `POST /sso/handoff-code` with `Authorization: Bearer …`, `app_id`, and `redirect_uri` to create a single-use destination callback URL before browser navigation; the response never contains a bearer token in the URL - app-switcher preferences persist user-level launcher choices and platform shell theme through `GET` and `PUT /api/app-switcher/preferences`, including `favorites`, `hidden`, `tileSize`, and optional `theme: "light" | "dark"` - first-party service-scoped login resolves a personal active context to the single organization membership that has access to the requested organization-only service before issuing the destination token - the retired browser `/sso/handoff` bridge is not part of the active route contract - developer-console workspaces are Auth organizations under the hood, so developer app records and API keys stay org-scoped and reuse the same ownership model as the rest of the platform - `POST /register` can now seed a developer workspace when called with `developerWorkspace=true` and `createOrganization=true`, assigning the creator as org `owner` - Topolo Developers owns the signed `/api/developer-console/*` route family directly. Auth no longer publishes `/api/developer-portal/*` or the older review aliases and remains the identity, central API-key, and approved-app registration authority used by that console - Topolo Developers is the action authoring, publication, and discovery surface. Public SDK/CLI/MCP consumers read `GET /api/actions/catalog` from Developers; Developers uses Auth only for current credential entitlement and permission projection, while execution goes to the owning application API - developer workspaces should continue to read service scope catalogs from Auth instead of shipping app-local scope lists, and suspended or revoked developer workspaces should be blocked from mutating central API keys through the same Auth endpoints - app availability and entitlement repair flows use Auth catalog tables as the source of truth. Split D1 routing must classify `app_availability` as catalog-owned, and repair/backfill routes must not write availability state through the wrong database role. - `GET /api/users/:userId/export` and `GET /api/organizations/:orgId/export` return portable Auth-owned records while excluding password hashes, MFA secrets, backup codes, reset tokens, invitation codes, API-key hashes, and OAuth client-secret hashes. Their public action IDs are `app_topolo_auth.users.export` and `app_topolo_auth.organizations.export`. - `DELETE /api/users/:userId/permanent` and `DELETE /api/organizations/:orgId/permanent` are destructive, confirmation-required actions. Organization permanent deletion requires prior soft deletion and rejects the platform administration organization; their action IDs are `app_topolo_auth.users.delete_permanently` and `app_topolo_auth.organizations.delete_permanently`. - Auth's scheduled privacy maintenance permanently removes user and organization tombstones after 30 days and removes audit records after 365 days in batches of 100. ## Internal billing-plane provisioning These routes back the TopoloOne signup-from-checkout flow. They authenticate with a keyless S2S service token (`verifyServiceToken`) and are restricted to billing-plane app identities by slug allowlist (`topolo-pay`, `topolo-one-website`, `topolo-one-api`); no user JWT is involved. Because Auth is the token issuer, it verifies these inbound service tokens against its own LOCAL JWKS rather than HTTP-fetching its own hostname. - `POST /api/internal/provision-from-checkout` — passwordless workspace provisioning from a completed checkout. Creates the organization plus a passwordless owner identity (role `owner`, empty password hash), seeds the org's app entitlement on `organizations.settings.appEntitlement`, grants the default platform services plus the target service, and issues a single-use magic-login token whose consume URL is returned as `loginUrl` so the marketing success page can drop the user straight into the dashboard with no "Create Account" screen. Idempotent by email: it resolves the owner's existing org by membership (the org they own, not just active context) and re-issues a fresh login token instead of creating a duplicate workspace. On FIRST provision only (`created: true`) it also emits a separate, longer-TTL safety-net magic link by email (this emailed token KEEPS the anti-prefetch interstitial). Request body: `email`, `workspaceName` (or `company`), `appId`, `redirectUri` (validated against the service entrypoint), optional `name`, and an entitlement snapshot (`mode` of `count` | `all` | `free`, optional `paidAppCount`, optional `appSlugs`). Returns `{ orgId, userId, created, loginUrl, expiresAt }`. - `GET /api/internal/organizations/slug-availability?slug=` — live workspace-URL availability for the signup form's Google-style "is this taken?" check. Validates format (lowercase alphanumeric with internal hyphens, 3–48 chars), screens a reserved-subdomain set, then checks `getOrganizationBySlug`. Read-only and idempotent; returns `{ available, slug, reason }` with `reason` one of `available`, `taken`, `invalid`, `reserved`, or `empty`. The magic-login token issued by provisioning sets the new `magic_login_tokens.skip_interstitial` flag (migration `0029`). A trusted in-session token auto-consumes on `GET /magic-link/consume`, skipping the anti-prefetch "Confirm sign-in" interstitial that protects email-delivered links; both the GET fast path and the POST confirmation share `completeMagicLinkSignIn`. ## Change Log / Verification - Verified the four privacy lifecycle actions on staging on 2026-08-01 at Auth source `2f0298ee46551fdd41acd5378d8f4cb702a8784f` and Worker version `15b4eb4d-ece0-451c-a042-887a21c93d2a`. Live exports omitted forbidden secrets; disposable organization `org_RA6ZOeAWaYWH` was exported, soft-deleted, permanently purged with 885 written rows, then returned `404` from both get and export while direct affected-store checks returned zero residual rows. - Reconciled Auth API reference on 2026-06-28 against `topolo-platform/core/TopoloAuth` through `20653c79` and `2eb51859`; documented internal services export, bulk availability, app-id mapping, scoped catalog `app_id` projection, and catalog-owned app availability routing. ## API Keys Canonical URL: https://docs.topolo.app/platform/api-keys Central API key model, scope ownership, and resource binding behavior across Topolo services. ## Ownership API key records, scope definitions, canonical workspace identity, and resource-binding decisions are centrally served by Topolo Auth. Topolo Developers publishes application resource-type metadata, while the shared `@topolo-io/api-key-management` package owns the management UI and consumes Auth through the shared Auth client. Applications must not maintain local scope catalogs, workspace identity copies, API-key forms, or management proxy routes. TopoloOne and Topolo Developers expose multi-application views for organization-wide credential administration. Every authenticated browser application also exposes the same shared application-mode screen from the account menu, limited to that application's service identity. ## Key model Each key has: - an owning organization - a target service - an explicit scope set - optional resource bindings - lifecycle state such as active or revoked ## Resource bindings Some services support resource-level constraints. First-party applications use the canonical Auth-owned `workspace` resource even when the product calls it a brand, project, venue, merchant, or another domain term. Auth validates requested bindings at key creation and update time. Before rendering a key form or planning a key mutation, clients call `api_keys.options` for the selected application in the active organization. The response is user-specific and contains the only scopes and resources the caller may bind. Resource rows include the caller's `accessLevel` and `allowedScopes`; duplicate resource-type declarations are collapsed into one selector. Applications must not inject their own workspace, brand, project, or other resource lists into the API-key UI. Auth queries its canonical active workspaces for the exact application and organization, then applies the same ownership and grant policy used for protected workspace requests. This prevents stale app-local lists or resources from another organization appearing in the form. ## Consumer modes - **Application mode:** the current app supplies its canonical app ID and organization context. The shared screen shows only that app's keys, scopes, and bindable resources. - **Multi-application mode:** TopoloOne and Topolo Developers supply the organization's Auth-backed service catalog. Users can select an application and manage credentials across the organization. ## Current consumer flow 1. The host application supplies organization context and either one service or an Auth-backed service list. 2. The shared screen requests `api_keys.options` from Auth for the selected service and exact active organization. 3. The user selects zero or more authorized resources, then selects scopes from the intersection allowed across those resources. With no resource binding, only organization-wide scopes are available. 4. Auth repeats the same authorization calculation for create and update requests; browser state is never authoritative. 5. Auth re-evaluates the key owner's current application, organization, ownership, and grant access during introspection. Revoked or reduced access immediately narrows or invalidates the key. ## Access levels - A workspace owner receives the application's read and write API-key scopes for that owned workspace, excluding management scopes. - A `read_write` workspace grant receives read and write scopes, excluding admin or management scopes. - A `read` workspace grant receives read scopes only. - Organization roles remain bounded to workspaces they own or have been explicitly granted. Platform operators authenticated through the Auth `admin` organization may inspect and bind all active workspaces in an explicitly selected organization with management scopes. - A key bound to multiple resources receives only scopes allowed by every selected resource. - Users manage their own keys. Holders of Auth's `api_keys:admin` permission may list and revoke other users' keys but cannot edit them. ## Operational note Resource-binding catalogs and key mutations are centralized in Auth. Reusable presentation and interaction behavior belongs in `@topolo-io/api-key-management`; app-local code should only provide identity, organization context, permissions, and placement. ## Change Log / Verification - Corrected the public resource-binding model on 2026-07-29: Auth derives bindable resources directly from canonical workspaces rather than refreshing an app-owned provider or reading a shadow resource catalog (`topolo-platform` staging `8e4879af38ea`). - Reconciled API-key discovery through `topolo-platform` `origin/staging` `51ff2d839e86` on 2026-07-29: static actions remain permission-filtered, while runtime-authorized actions are discoverable and re-authorized by their target for the concrete request. - Reconciled this page against `topolo-platform` `origin/staging` `24c646847b23` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Added the user-specific `api_keys.options` preflight, ownership/grant scope caps, exact-organization resource filtering, duplicate resource-type deduplication, own-key lifecycle, and dynamic introspection enforcement on 2026-07-14. - Added clean-room agent resource-type discovery and identifier-resolution guidance on 2026-07-14. - Standardized API-key management on 2026-07-12: TopoloOne and Topolo Developers use the shared multi-application screen, every authenticated browser application's account menu opens the AppShell-owned app-local mode, and obsolete hand-built browser clients and proxy routes were removed. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. ## Platform Architecture Canonical URL: https://docs.topolo.app/platform/architecture Top-level platform shape, authority boundaries, and how the unified documentation platform maps onto the codebase. ## Authority boundaries - **Topolo Auth** is authoritative for identity, organization access, service registration, service permissions, and API key catalogs. - **TopoloOne** is the operator-facing control surface for those shared capabilities. - **Application services** remain authoritative for their own data models and APIs. ## Shared platform surfaces - service registry - user and organization resolution - API keys - resource-bound API access - first-party browser auth transport through `X-App-ID` headers and `app_id` callback bodies - deployment and operational conventions ## Documentation model This docs site is built from: - public content for developers - internal content for operators and agents, exposed under `/internal` only for Topolo-org members - a system registry collection for canonical identifiers - generated API summaries from source-controlled OpenAPI specs where available ## Priority systems The first migration wave covers Topolo Auth, TopoloOne, Socialize, TopoloCRM, and shared platform concepts. Additional applications can be added without changing the content contract. ## Change Log / Verification - Reconciled the Auth-owned workspace model, target-specific Cloudflare configuration, and fail-closed action-catalog boundary through `topolo-platform` `origin/staging` `51ff2d839e86` on 2026-07-29. - Reconciled this page against `topolo-platform` `origin/staging` `24c646847b23` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Verified on 2026-07-05 that first-party browser login, refresh, and pre-boot SSO handoff use the `X-App-ID` / `app_id` auth contract instead of the retired `X-App-ID` browser header. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. ## Topolo Platform Deep Dive Canonical URL: https://docs.topolo.app/platform/deep-dive Non-technical deep dive into what the Topolo Platform is, who it serves, what sits inside its scope, and how the product portfolio fits together. ## What Topolo Is Topolo is a connected operating platform for businesses, builders, agents, and customers. It is not a single app. It is a full product ecosystem built around one shared account, one shared identity layer, one shared application catalog, and a growing set of first-party products that can work together instead of behaving like isolated software tools. At the center of Topolo is the idea that modern organizations do not need another disconnected dashboard for every workflow. They need a trusted environment where people, teams, customers, suppliers, AI agents, data, communication, payments, operations, and application access can all be understood in relation to one another. Topolo provides that environment. The platform includes public-facing applications, internal operator tools, mobile applications, developer tools, AI workforce infrastructure, communication products, commerce products, identity and access controls, documentation, deployment governance, and system registries. Some products are mature, some are being actively shaped, and some exist as platform-owned foundations for future applications. The scope is intentionally broad because Topolo is designed as a platform, not as a narrow point solution. In plain terms: Topolo is the shared foundation that lets a business run work, communicate, sell, support customers, manage teams, publish applications, control access, and coordinate human plus AI activity through one connected environment. ## The Simple Version Topolo can be understood through five simple statements. 1. Topolo gives every person one durable identity. 2. That identity can belong to no organization, one organization, many organizations, or household-style personal contexts. 3. Applications decide what that person can actually use based on membership, entitlement, role, invitation, plan, or local product rules. 4. Topolo provides shared platform services so applications do not have to reinvent login, app switching, billing boundaries, notifications, provider connections, documentation, deployment governance, and operational oversight. 5. The long-term scope is a connected application ecosystem where first-party apps, developer apps, customer-specific installations, mobile tools, and AI agents can operate under the same trusted platform model. This means Topolo is both a product suite and a platform layer. The product suite gives users useful applications. The platform layer makes those applications coherent, governable, and extensible. ## Why The Platform Exists Most business software stacks grow by accident. A company adds a CRM, then a payment tool, then a messaging tool, then an operations dashboard, then a support system, then a reporting product, then AI assistants. Each product has its own account model, permissions, billing rules, notifications, data boundaries, and integration assumptions. The result is friction: users repeat setup, operators lose visibility, developers rebuild common plumbing, and organizations struggle to understand who has access to what. Topolo exists to reduce that fragmentation. The platform is built around a different premise: shared capabilities should be platform-owned, while product-specific workflows should stay inside the product that understands them best. A CRM should own CRM records. A commerce product should own restaurant, order, venue, and catalog workflows. A social publishing product should own brand campaigns and scheduled content. But none of those apps should need to invent their own identity provider, app launcher, role model, staging environment rules, canonical documentation model, provider credential governance, or cross-app access story. Topolo separates the common foundation from the product workflow. That is the core platform strategy. ## The Product Promise Topolo is intended to feel like one connected workspace rather than a pile of unrelated tools. A person should be able to sign in once, choose the right personal or organization context, open the applications they are allowed to use, and move between them without thinking about separate accounts. An owner should understand which people, agents, and applications belong to their organization. A developer should be able to register and operate an app without rebuilding the whole platform foundation. An operator should be able to inspect system health, access, documentation, and deployment state from canonical sources instead of hunting through local notes. An AI agent should have accountable ownership, limited access, and a clear operating boundary. That promise depends on scope discipline. Topolo does not try to make every app store all data in one central database or make every product behave the same way. Instead, it defines what the platform owns, what each app owns, and how those boundaries are made visible. ## Who Topolo Serves Topolo has several audiences, and the platform scope is shaped around all of them. ### Business Owners And Operators Owners need to know who is in the organization, which applications are active, which services are paid or enabled, where customer-facing work is happening, and what operational issues need attention. TopoloOne, Topolo Admin, CloudControl, Status, Nexus, and the docs platform exist partly to make those questions answerable. ### Teams And Employees Employees need access to the applications required for their role without managing separate accounts for every product. They may use CRM, Commerce, Messaging, Mail, Calendar, Roadmapper, Socialize, Support, Pay, Quro, or other apps depending on the organization. ### Developers And App Publishers Developers need a place to register applications, configure public visibility, manage app metadata, integrate with Topolo identity, and participate in the broader application ecosystem. Topolo Developers is the product boundary for that work. ### Consumers And Personal Users Topolo identity is not limited to organization members. A person can have a Topolo account without being attached to an organization. That matters for personal surfaces, household-capable flows, future consumer products, invitations, external app login, and account recovery. ### AI Agents And Automated Workers Topolo treats AI workforce participation as part of the platform scope, not as an untracked sidecar. Agents are expected to have accountable human ownership, limited service access, revocable credentials, and clear auditability. This lets AI agents act inside workflows without pretending to be ordinary human users. ### Internal Operators Internal Topolo operators need system maps, staging environments, deployment controls, canonical docs, production-readiness evidence, app health, support visibility, and safe workflows for improving the platform. The platform includes internal applications and runbooks because operating the system is part of the product. ## The Main Platform Idea: Identity Is Not Access One of the most important Topolo concepts is that identity and access are separate. A Topolo account proves who someone is. It does not automatically prove that the person can use every app. This distinction keeps the platform flexible. A person might: - have a personal Topolo account and no organization membership - belong to one business organization - belong to several organizations - participate in a household or personal sharing context - use a free first-party app - use a paid first-party app through an organization - enter a product through an invitation - sign in to a third-party app using Topolo identity - act as the accountable owner for one or more AI agents Each of those cases starts with identity, but each has a different access story. The platform uses identity to know who the person is. Membership explains where they belong. Entitlement explains what they can use. Billing explains who pays. Launcher eligibility explains whether the person should see cross-app switching. Product-specific rules explain what they can do inside a given application. Keeping those ideas separate is central to Topolo's scope. ## The Workspace Model Topolo is designed for more than one kind of working context. ### Personal Context Every person can have a personal context. This allows Topolo to support users before they join an organization, after they leave one, or when they use personal or household-oriented products. It also helps preserve account continuity because the person is not only defined by a work email or company seat. ### Organization Context Organizations represent businesses, teams, customers, or workspaces that own app access, roles, seats, billing relationships, operational data, and product configuration. Most first-party business apps operate in an organization context. ### Household And Personal Sharing Contexts Some personal flows need household-style relationships, such as families, dependents, caregivers, or shared personal profiles. Topolo treats these as attached personal relationships rather than as ordinary business organizations. ### Service-Local Contexts Some applications may own their own local membership model. For example, a learner, requester, guest, partner, supplier, respondent, or public participant may authenticate through Topolo but still receive product access from the application that invited or enrolled them. ### Developer Workspace Context Developers have their own workspace model for building, publishing, and managing applications. A developer workspace is not the same thing as an ordinary paid suite seat, even though it still uses Topolo identity. This context model is what allows Topolo to support internal teams, external customers, developers, consumers, and agents without forcing every person into the same organization-shaped box. ## Platform Scope At A Glance The Topolo Platform scope includes the following major layers. | Layer | What It Means In Non-Technical Terms | | --- | --- | | Identity and access | Who people are, where they belong, which apps they can use, and how sessions move across products. | | Application suite | First-party apps for work, communication, commerce, support, content, operations, payments, documents, learning, and more. | | Developer platform | Tools for registering, reviewing, publishing, and operating applications built on or connected to Topolo. | | AI workforce | Agent identities, ownership, access limits, credentials, workflow participation, and human accountability. | | Billing and spend boundaries | Who pays, which seats or agents count, and how platform-level provider spend is controlled. | | Notifications and communication | Shared event, email, messaging, and preference patterns across applications. | | Provider connections | Shared governance for external providers such as AI, email, social, payment, messaging, and other third-party services. | | Mobile and device surfaces | Mobile apps, managed devices, tablets, Android surfaces, local venue runtimes, and device catalog consumption. | | Deployment and installations | Staging, production, future enterprise installations, environment isolation, deploy targets, and operational verification. | | Documentation and registry | Canonical docs, application inventory, service registry, system ownership, API coverage, and operational handbooks. | | Internal operations | Admin, CloudControl, Status, seed data, bug reporting, issue improvement, support, and platform health workflows. | The platform scope is broad because each layer affects whether the ecosystem behaves like one product family or many disconnected products. ## What Is In Scope ### One Shared Identity Layer Topolo Auth is the shared identity and access foundation. It owns the durable account, credentials, account recovery, organization membership, service registration, permission catalogs, and the platform view of the current user context. This does not mean Auth owns every app's data. It means Auth provides the trusted account and access starting point. ### A Unified Application Experience Topolo applications should feel connected through shared login, app switching, account menus, loading states, design language, and platform chrome. The shared application shell and UI foundation exist so first-party apps do not drift into unrelated visual and navigation models. ### First-Party Application Portfolio The first-party application portfolio is part of the platform scope. It includes products for CRM, commerce, communication, scheduling, content, payments, documents, forms, surveys, learning, support, social publishing, email, roadmap planning, device management, and more. The portfolio is not limited to only the currently most mature apps. The system registry represents the broader platform surface so the docs, app catalog, and operational tooling can track what exists and where it belongs. ### Developer And Third-Party App Participation Topolo is not only for apps built by Topolo. The platform includes a developer surface where outside or internal developers can register applications, configure identity integration, manage visibility, and participate in marketplace or catalog workflows. Third-party apps can use Topolo identity, but they do not automatically become part of the first-party suite. They must still own their local customer, subscription, invitation, and product access rules unless Topolo explicitly owns those rules. ### AI Agent Participation AI agents are in scope as platform actors. Topolo expects agent work to be tied to accountable human owners, service access, audit history, revocation, and product policies. This makes agent participation more like a governed workforce model than a collection of anonymous automation scripts. ### Cross-App Operations Topolo includes the internal control surfaces required to keep the ecosystem coherent: Admin for platform and organization administration, CloudControl for deployment and project metadata, Status for health, Docs for canonical knowledge, BugFix and improvement surfaces for issue loops, and Seed for staging-only data setup. ### Environment And Installation Boundaries Topolo production, staging, preview, sandbox, and future enterprise deployments are part of platform scope. An environment is not just a hostname. It includes data stores, secrets, Auth issuer, service registry namespace, provider configuration, seed rules, and deploy governance. ### Canonical Documentation TopoloDocs is part of the platform itself because the docs define the current source of truth. Product behavior, application ownership, access boundaries, deployment shape, public reference, internal handbooks, runbooks, and system registry metadata all need to live in one canonical place. ## What Is Not In Scope Clear boundaries matter as much as broad scope. Topolo identity does not automatically grant access to every app. A signed-in person still needs the correct membership, invitation, role, plan, organization install, free-app policy, or product-specific entitlement. Topolo Auth does not own every product record. CRM owns CRM workflows. Commerce owns commerce data. Socialize owns brand and campaign workflows. Mail owns mailbox behavior. Roadmapper owns roadmap and project planning behavior. The platform coordinates access and shared capabilities; each product remains responsible for its domain. A third-party application using Topolo login does not become a first-party Topolo app by default. It remains responsible for its own customers, plans, invitations, and product rules unless a specific Topolo marketplace or platform policy says otherwise. A staging environment, enterprise install, sandbox, or customer deployment is not a separate application. It is an installation or environment boundary for the same platform model. A local duplicate folder, helper workspace, generated output directory, or deployment helper is not a product boundary. The platform registry should describe real systems, not temporary operator machine state. The platform is not trying to flatten every application into one mega-app. The goal is shared foundation plus clear product ownership, not one giant interface where every workflow is forced into the same model. ## Product Families Topolo's application portfolio can be understood as several product families. ### Platform Control And Workspace These products help people enter, administer, and understand the platform. Topolo Auth handles identity, login, access context, service registration, permission foundations, and account continuity. TopoloOne is the unified personal and organization workspace. It is the front door for app discovery, current context, billing-related owner workflows, personal profile and family-oriented flows, authenticated app catalog experiences, and cross-platform workspace activity. Topolo Admin is the administrative surface for organizations, users, services, role assignment, support visibility, app-centric access, audit views, billing previews, and operator handoff into internal tools. Topolo Developers is the application publisher and developer workspace. It supports app registration, public signup for developers, app store metadata, mobile artifacts, submissions, visibility, pricing, and internal review workflows. CloudControl is the internal deployment and operational metadata layer. It tracks project metadata, deployment targets, Cloudflare resources, histories, and operator workflows. TopoloDocs is the canonical documentation and registry surface. It is where public docs, internal handbooks, system records, app reference, and machine-readable inventory come together. ### Core Business Applications These products support everyday business workflows. TopoloCRM covers customer relationship management, workflows, records, and sales or SDR-related control surfaces. TopoloCommerce covers multi-vertical commerce operations, including venue operations, guest ordering, public runtime, station workflows, team execution, catalogs, queue control, shared tabs, staff review, translation, local venue edge behavior, and device-aware operations. Topolo Forecast supports cash-flow and profit-and-loss planning. Topolo Pay handles payment-related application behavior, orders, webhooks, and administrative payment surfaces. Topolo Inventory manages items, locations, stock movement, and low-stock reporting. Topolo People supports employee records, onboarding, people operations, document generation, and signature-connected HR-style workflows. Topolo Books, Capacity, Success, and related business surfaces are part of the broader first-party application set as they mature into fuller product responsibilities. ### Work Planning, Documents, And Knowledge These products help teams plan, write, decide, and deliver work. Topolo Roadmapper supports roadmap and project management, AI-assisted onboarding, project planning sessions, hierarchy-wide sharing, guest editing auditability, and narrative presentation delivery. TopoloCompose is an AI-native document generation, revision, styling, export, and cross-app document intent workspace. It supports contracts, papers, reports, policies, letterheads, proposals, employee documents, and formal documents. Topolo Forms and Topolo Survey support structured intake, published public collection links, response capture, and reporting. Topolo Sign handles electronic signature templates, envelopes, recipient signing links, and audit records. Topolo Learn supports multi-tenant learning businesses, cohorts, assessments, evidence packs, certification, and enterprise seat management. ### Communication And Customer Contact These products support conversation, outbound communication, and customer interaction. Topolo Mail is the first-party email client for organization-scoped shared mailboxes, inbound routing, outbound delivery, agent-assisted drafting, and protected mailbox access. Topolo Messaging is the WhatsApp Business messaging surface for multi-number brand workspaces, shared inboxes, campaigns, automations, provider webhooks, and cross-application messaging boundaries. Topolo Chat supports collaboration through channels, direct messages, meetings, guests, and remote assist. Topolo Calendar supports scheduling, booking pages, embeddable widgets, and cross-app event feeds. Topolo Voice provides reusable synthetic voice profiles, authorized voice samples, render eligibility, revocation state, automated outreach, and inbound voice runtime. Topolo Notify is the platform notification foundation for transactional events, templates, preferences, delivery behavior, and cross-app notification flows. ### Growth, Publishing, And Brand Work These products support marketing, content, social presence, and public-facing growth. Socialize is the social publishing and campaign product. It owns brand-scoped workflows, provider connections, campaigns, scheduling, and publishing logic. Topolo Social Studio is the studio-branded production surface for social planning, generation, review, and export. Topolo Bytes manages media and assets for upload, organization, review, and sharing. Topolo Quro creates QR codes, redirects, scan tracking, and related campaign surfaces. Topolo Web is the website platform for signed-in site studios, agent planning, publishing snapshots, domains, forms, assets, and launch QA. Topolo Director coordinates demo runbooks, human recording chunks, off-record controls, footage archive handoff, narration, voice render requests, and readiness gates. ### Device, Mobile, And Physical-World Operations Topolo is not only browser software. Topolo Mobile Apps is the retained source root for first-party Flutter mobile applications and smaller ecosystem worker APIs. Topolo MDM spans device APIs, tenant realtime hubs, operator console surfaces, Android device policy work, and mobile scaffolds. Topolo Device Platform covers Nodo host acquisition, feed delivery, analytics, Android playback, and device-side app catalog consumption. Commerce also extends into tablets, venue stations, local runtime behavior, and device-aware queue workflows. Those physical-world touchpoints are part of why the platform needs mobile, device, and local operation scope. ### Governance, Safety, And Internal Improvement These products keep the platform observable and improvable. Topolo Status provides public status and monitoring. Improve Topolo and BugFix-related surfaces support shared contribution, issue triage, product improvement, AI analysis, and pull-request automation. Topolo Seed is a staging-only control plane for realistic synthetic seed packs, usage simulation, burst runs, and reset operations. Topolo D1 Backup handles production database snapshot workflows into backup storage. Topolo Consent covers privacy permissioning, consent, global privacy controls, native SDKs, cookie scanning, data subject requests, and audit evidence. Security, privacy, docs governance, and deployment runbooks sit inside platform scope because they determine whether the product family can be operated responsibly. ## How The Pieces Fit Together The easiest way to understand Topolo is to follow a typical organization. A business owner joins Topolo and creates or enters an organization. Topolo Auth knows who they are. TopoloOne gives them a workspace. Topolo Admin lets them manage organization users, app access, and support-facing identity context. The app catalog shows which applications are available. The owner can enable or use products such as CRM, Commerce, Mail, Messaging, Calendar, Roadmapper, Socialize, Pay, or Support depending on the business need. An employee signs in with a Topolo account. If they belong to the organization and have the right service access, they see the applications relevant to their role. They can switch between those apps through shared platform chrome. They do not need to understand which product owns which data store. The platform handles the shared account and app eligibility, while each product handles its domain workflow. A developer signs up through Topolo Developers. Their account is still a Topolo identity, but their developer workspace has a different purpose from an ordinary paid suite seat. They can register applications, manage metadata, configure visibility, and eventually participate in the application ecosystem. A customer, supplier, learner, requester, or guest may enter through a product invitation or public flow. They may authenticate through Topolo without becoming a full organization user. The application that invited them owns the local access decision. An AI agent participates in work through a governed identity model. It has an accountable human owner, limited credentials, service-scoped permissions, and revocation paths. It can act in workflows without hiding who is accountable for its behavior. An internal operator uses CloudControl, Docs, Admin, Status, Seed, and runbooks to understand what is deployed, where it is deployed, what systems exist, what access boundaries apply, and whether staging and production match the intended platform shape. Those flows describe the point of the platform: different participants, one coherent operating model. ## The Role Of TopoloOne TopoloOne is the main workspace experience. It is not simply a dashboard in the narrow sense. It is the user's live platform home for personal and organization context, app discovery, app catalog behavior, billing-facing owner workflows, developer acquisition surfaces, profile and family-related flows, and authenticated workspace activity. TopoloOne matters because a platform with many products needs an entrypoint that makes the whole suite navigable. Without it, users would have to know the exact app URL, entitlement state, organization context, and login status for every tool. TopoloOne should answer the human question: "Where am I in Topolo, and what can I do from here?" ## The Role Of Topolo Auth Topolo Auth is the identity and access backbone. It owns login, account continuity, sessions, organization memberships, personal contexts, household-related account relationships, service registration, permission foundations, and access hydration for applications. In non-technical terms, Auth answers: - Who is this person? - Which personal or organization context are they currently using? - Which organizations or household relationships are attached to the identity? - Which services are they allowed to enter from the platform's point of view? - Which identity class are they: organization member, personal user, service-local participant, developer workspace user, agent employee, or another supported principal? Auth does not decide every business action inside every app. It provides the account and access context that applications use before applying their own product rules. ## The Role Of Topolo Developers Topolo Developers is the publishing and developer control surface. It exists because the platform scope includes apps built by Topolo and apps built by others. Developers need a place to define what their app is, what callbacks or login routes it uses, what scopes it requests, how visible it should be, which marketplaces or catalog areas it belongs in, what mobile artifacts exist, and whether internal review is complete. The developer platform also protects the broader ecosystem. It separates draft, developer-only, reviewed, verified, internal, public, suspended, and other states so a registered app does not automatically become a trusted public platform app. ## The Role Of Nexus Topolo Nexus is the gateway and usage-management layer for standardized provider access. In business terms, it helps avoid every app managing external AI, email, payment, social, or other provider relationships in a completely separate way. Nexus scope includes provider credential and connection inventory, AI and model preference access, usage controls, and platform-level spend boundaries. This matters because as AI and provider-backed features spread across the suite, spend and credential governance become platform issues rather than app-local details. ## The Role Of CloudControl CloudControl is the operational map for deployments and resources. It helps Topolo know which app deploys where, which environment it belongs to, what project metadata exists, and how staging or production should be resolved. For a non-technical reader, CloudControl exists so deployment knowledge does not live in memory, terminal history, or scattered notes. It turns operational reality into a discoverable control-plane view. ## The Role Of TopoloDocs TopoloDocs is not just documentation in the marketing sense. It is the canonical source of truth for platform behavior, application architecture, public reference, internal handbooks, deployment conventions, runbooks, and system registry metadata. When Topolo changes behavior, the docs should change too. That keeps humans, agents, operators, and developers aligned on the current platform reality. ## Scope By Relationship Type Topolo must support several relationship types at once. ### Person To Platform The person has a Topolo account. The account persists even if organization membership changes. Recovery email, credentials, identity continuity, and personal context belong here. ### Person To Organization The person may belong to one or more organizations. Each organization can grant roles, services, seats, app access, billing ownership, and product-specific permissions. ### Person To Application The person may have access to one app but not another. Access may come from an organization grant, app-owned invite, plan, role bundle, free-app policy, third-party subscription, or product-specific onboarding. ### Organization To Application An organization may install, enable, pay for, configure, or restrict applications. The organization relationship decides what is available to its users, but each app still owns its domain behavior. ### Developer To Application A developer may own an app listing, a client, a submission, pricing, review metadata, callback configuration, mobile artifact, or publishing workflow. That does not make the developer a suite operator. ### Human To Agent An AI agent should have an accountable human owner. That owner may be responsible for agent intent, review, approval, and audit context, but the agent is still its own principal for access and billing purposes. ### Platform To Installation The same platform can exist in production, staging, preview, sandbox, or future enterprise customer installations. Each installation must isolate data, secrets, app identity, provider configuration, and deployment rules. ## Scope By Business Capability Topolo's scope can also be described by business capability. ### Run The Business Commerce, CRM, Pay, Inventory, Forecast, People, Support, Calendar, Mail, Messaging, and related products help organizations run everyday work. ### Grow The Business Socialize, Social Studio, Bytes, Quro, Web, Director, Roadmapper, and content-related products help organizations publish, campaign, communicate, present, and grow. ### Govern The Business Auth, Admin, Nexus, Consent, Status, CloudControl, Docs, Seed, Backup, and security or privacy handbooks provide governance, visibility, compliance, operational safety, and platform control. ### Build On The Platform Developers, service registry, API reference, application catalog, SDKs, MCP and CLI tooling, and third-party login support allow applications and integrations to be built on top of Topolo. ### Coordinate Human And AI Work Agent, Nexus, Roadmapper, Compose, Support, BugFix, Mail, Voice, and other AI-aware surfaces form the emerging AI workforce and automation layer. The platform treats those capabilities as governed work, not loose automation. ## Why The Application Catalog Is Broad Topolo's catalog is intentionally broader than a launch-week product list. A platform needs to know about products even while they are still maturing, being consolidated, or waiting for deeper docs coverage. The catalog answers: - What exists? - Which system owns it? - Is it public, internal, staging-only, or inventory-level? - Which repo or source root owns it? - Which docs explain it? - Which app IDs or hosts belong to it? - Which security, privacy, and operational review state applies? That is why the platform tracks products such as core apps, internal apps, mobile roots, device-platform surfaces, staging-only seed controls, and operations tools. The catalog is not only a marketing page. It is a map of the platform surface. ## Trust And Visibility Topolo separates trust from visibility. Trust is about confidence: Is this app internal? Reviewed? Verified? Suspended? Unreviewed? Is the owner known? Are callbacks and requested scopes appropriate? Visibility is about who can use or see the app: everyone, only the developer organization, only internal operators, a specific customer, a staging environment, or nobody while the app is paused. This split protects the platform from treating every registered app as production-ready. It also lets developer work happen without exposing unfinished tools as normal customer applications. ## Billing And Seats Billing is part of platform scope, but billing is not the same thing as identity. An organization member may count as a billable seat depending on their role and plan. A guest, household member, service-local participant, suspended user, or unaffiliated personal user should not automatically count as a paid organization seat. AI agents may have their own billable behavior. An agent should not silently count as the same thing as its human owner. Changing agent ownership changes accountability; it should not hide or double-count seats. Some products may own subscription details directly. Some may bill through organization plans. Some third-party apps may own their own customer relationship. Some apps may be free. The platform's job is to make the boundary clear rather than forcing every commercial model into one rule. ## Notifications And Communication Notifications are platform scope because every major product eventually needs to tell someone something: an invoice failed, a ticket changed, a campaign is ready, an order needs attention, a document needs a signature, a booking happened, or an AI agent needs approval. Topolo's notification scope includes events, templates, channels, delivery preferences, organization policies, billing-related notices, and user-level communication rules. Individual apps still own the meaning of their workflow events, but the platform provides shared patterns for delivery and preferences. ## Privacy, Consent, And Security Scope Topolo handles sensitive categories of data: identity, organization information, payments, customer content, provider credentials, communications, telemetry, personal data, and potentially household-related data. That makes privacy and security platform-wide concerns. The platform scope includes consent, privacy permissioning, data subject request paths, provider credential control, environment isolation, access review, security assurance evidence, and docs that define expected boundaries. This does not mean every privacy feature is complete across every product. It means the platform recognizes privacy and security as shared product responsibilities, not afterthoughts inside isolated apps. ## Deployment And Environment Scope Topolo production and staging are separate platform environments. Staging is not just a test URL against production data. It is intended to be a full platform mirror with its own account strategy, domains, data, secrets, Auth issuer, service registry namespace, provider configuration, and seed policy. This matters because a platform cannot be safely improved if staging does not represent real system behavior. Topolo's environment scope supports staging-first validation, future enterprise installations, sandbox environments, preview deployments, and controlled production promotion. ## Mobile, Device, And Physical Operations Scope Topolo includes browser apps, mobile apps, device-related applications, and physical-world operations. This matters because some important workflows happen away from a desktop screen. Commerce station workflows, Android playback, managed devices, venue edge behavior, tablet-first execution, mobile apps, voice flows, and device catalog consumption are all examples of platform-adjacent product surfaces. They create access, identity, deployment, data, support, and operational requirements that the platform must understand. ## Developer Ecosystem Scope Topolo's developer ecosystem includes public docs, app registration, app review, app identity, allowed callbacks, scopes, app metadata, catalog entries, mobile artifacts, pricing controls, submission workflows, and future marketplace behavior. The key principle is that developers can build with Topolo without becoming unbounded platform operators. Developer-owned apps have their own lifecycle, trust state, visibility rules, and local customer responsibilities. ## AI Workforce Scope Topolo's AI workforce scope is intentionally broader than chatbots. AI agents may help plan roadmaps, write documents, answer support, draft mail, generate content, triage bugs, propose fixes, trigger workflow steps, summarize context, or coordinate approvals. To make that safe, the platform needs a model for agent identity, agent ownership, credentials, service access, revocation, audit, and billing. The platform treats an agent as an accountable participant in work. It should not be an invisible script with unlimited access or a borrowed human login. ## Operational Scope The platform includes how Topolo is operated. That means deployment records, staging checks, production health, system documentation, app registries, support views, bug reporting, seed data, backups, privacy review, security assurance, and runbooks are all part of scope. This is important because a platform is not only what users click. It is also the set of practices and controls that keep the product coherent as it grows. ## A Practical Example Imagine a restaurant group using Topolo. The owner signs in through Topolo Auth and lands in TopoloOne. They enable Commerce for venue operations, Mail for shared inboxes, Messaging for WhatsApp customer communication, Calendar for bookings, Pay for payments, and Socialize for campaign publishing. Admin shows who can access each app. Nexus controls provider connections and AI or communication spend. Commerce owns menus, orders, venues, queues, and station workflows. Socialize owns brand campaigns. Mail owns shared mailboxes. Messaging owns WhatsApp inbox behavior. TopoloOne gives the owner a home across all of it. An employee can use only the apps their role allows. A guest ordering through a public venue page does not become a full organization user. A supplier or partner can use a product-specific portal without becoming an employee. An AI agent can help draft replies or inspect workflows only through governed access. An internal operator can inspect staging, docs, and system registry state when something behaves unexpectedly. That example shows the platform shape: shared identity and governance, separate product ownership, connected user experience. ## Another Practical Example Imagine a software builder using Topolo. They create a Topolo identity and enter Topolo Developers. They register an application, define its public metadata, configure login behavior, prepare review details, attach mobile artifacts if needed, and manage catalog visibility. Users of that app may sign in with Topolo identity, but the app still owns its local subscription or invitation rules unless it is explicitly promoted into a Topolo-owned commercial model. The developer benefits from Topolo identity and catalog infrastructure. The platform benefits because app trust, visibility, callbacks, consent, scopes, and review state are governed instead of being invisible. ## How Topolo Should Feel For users, Topolo should feel consistent but not generic. Apps should share the same account model, navigation expectations, app switching, and platform chrome, while still expressing their specific workflow clearly. For owners, Topolo should feel governable. They should be able to understand users, apps, access, billing-related state, provider connections, agent participation, and operational health. For developers, Topolo should feel extensible. They should be able to integrate without guessing the platform rules. For operators, Topolo should feel inspectable. The docs, system registry, deployments, staging targets, and runbooks should describe reality. For AI agents, Topolo should feel constrained and accountable. Agents should have clear owners, clear permissions, and clear limits. ## Platform Principles Topolo's scope is guided by several principles. ### Shared Foundation, Product Ownership The platform owns common infrastructure and shared contracts. Applications own their product workflows and domain data. ### Identity Before Entitlement A Topolo identity is the starting point. Actual app access must still be granted by the right source. ### Context Matters Personal, organization, household-style, developer, service-local, and agent contexts are different. The platform should preserve those differences instead of forcing every participant into one model. ### No Hidden Platform State Important behavior should be documented, registered, and discoverable. System ownership, app identity, deployment targets, docs paths, and operational status should not live only in memory. ### Staging First Significant platform changes should be proven in staging before production. Staging must be meaningful enough to catch real platform issues. ### Agents Are Accountable AI agents can participate in work, but they need ownership, access limits, revocation, and auditability. ### Developer Apps Need Trust Boundaries A registered app is not automatically a trusted public platform surface. Review state, visibility, callback ownership, and requested access all matter. ## Current Scope Summary Topolo currently spans: - identity, account recovery, organizations, personal contexts, household-aware flows, service-local identities, and app access boundaries - a large first-party application portfolio across business operations, growth, communications, commerce, documents, learning, support, payments, planning, devices, and internal operations - public docs, internal docs, system registry, service registry, API coverage, and machine-readable platform inventory - developer registration, app publishing, app review, catalog metadata, pricing controls, mobile artifacts, and third-party app participation - AI workforce identity, ownership, credentials, permissions, and product participation - shared platform shell, design language, app launcher, login, app switching, and user experience standards - staging, production, preview, sandbox, and future enterprise installation boundaries - platform-level provider connection and spend governance through Nexus and related control surfaces - notification, communication, consent, privacy, security assurance, and operational runbook foundations - mobile, device, venue, managed-device, and local runtime surfaces This is why Topolo should be described as a platform, not as a bundle of apps. ## Reading Map Read [Platform Architecture](/platform/architecture) for the short authority-boundary summary. Read [Application Catalog](/applications/catalog) for the current public portfolio map. Use the [Service Registry](/reference/service-registry) to locate canonical ownership, app identity, repos, hosts, and docs paths. Use app-specific public pages when you need a product-level view of a particular Topolo application. ## Change Log / Verification - Reconciled platform workspace ownership, action-catalog digest parity, runtime authorization, migration topology, and release evidence through `topolo-platform` `origin/staging` `51ff2d839e86` on 2026-07-29. - Reconciled this page against `topolo-platform` `origin/staging` `24c646847b23` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. - Added on 2026-05-08 as the public non-technical platform scope deep dive, aligned with the current platform registry, application catalog, identity and entitlement model, and deployment-scope docs. ## Partner Program Canonical URL: https://docs.topolo.app/partners/partner-program How agencies, dev shops, resellers, MSPs, and ISVs build, sell, and earn on the Topolo platform. > Program terms summarized on this page are indicative. Final commercial terms are > set out in the Topolo partner agreement. ## Why build and sell on Topolo Topolo is one platform with a single sign-up that gives an organization access to a full suite of business applications — CRM, calendar, messaging, payments, forecasting, and more — on a shared runtime with one identity, one bill, and one set of controls. For a partner, that shared foundation is the opportunity. Identity, billing, usage metering, payments, deployment, and hosting are already built and run by the platform. So when you build a custom application for a client on Topolo, you are not rebuilding plumbing — you are assembling on top of it. That collapses the cost and time of custom software and lets you deliver working applications in a fraction of the usual timeline. You bring the customer relationship and the domain expertise. Topolo provides the platform the solution runs on. Both sides earn on an ongoing basis. ## Who the program is for - **Build partners** — agencies, dev shops, and systems integrators that build custom applications for clients on the Topolo platform. - **Resellers and MSPs** — partners who sell Topolo to their customers and manage it for them as part of a broader service relationship. - **Referral partners** — accountants, consultants, and complementary vendors who refer customers to Topolo. - **Template and ISV partners** — partners who turn a build into a reusable application and publish it to the Topolo catalog for repeat distribution. ## How partners earn The program is designed so that the more value you deliver, the more you earn — across three revenue streams that can combine: - **You keep 100% of your services and build revenue.** Topolo does not take a cut of the work you do for your clients. What you charge to design, build, and implement is yours. - **Recurring revenue share on the platform usage you originate.** For accounts you bring to the platform, you earn an ongoing share of 20% of platform revenue (seats and usage) for the life of the relationship. Resellers and MSPs who prefer to own the customer billing relationship can instead take wholesale platform pricing and set their own retail price. - **Marketplace revenue for what you publish.** Turn a solution into a reusable vertical application, list it in the Topolo catalog, and earn recurring revenue on every customer who installs it. Topolo takes a 20% platform share, so you keep 80% of every sale. The model rewards both landing new customers and growing them over time. ## What you get - **Sandbox and demo environments** to build, test, and demonstrate on live platform tenants. - **SDK, documentation, and reference architectures** for building on the platform runtime. - **Deal registration and protection** so deals you source are yours — registered opportunities are protected from conflict. - **Partner directory listing and inbound referrals** once you are certified. - **Co-marketing and co-selling support** for strategic partners. ## Partner tiers | Tier | How you qualify | What it unlocks | | --- | --- | --- | | **Registered** | Sign up and accept the partner agreement | Deal registration, sandbox access, full documentation | | **Certified** | Complete the build certification | Directory listing, inbound referrals, higher revenue share | | **Strategic** | Sustained delivery and joint commitment | Co-marketing, co-selling, named partnership | ## Engagement models across the ecosystem Topolo supports a spectrum of ways customers get onto the platform, and partners have a clear, protected place in it: - **Self-serve** — customers sign up and subscribe directly for the standard app suite. - **Rapid MVP** — **TopoloMVP** is a fixed-fee, fast-turnaround service that delivers a working custom application starting at **$1,000 with a one-week turnaround**, built from platform primitives. It is the fastest demonstration of how quickly software ships on Topolo, and a common entry point that grows into larger builds. - **Partner-led builds** — agencies, dev shops, and ISVs deliver custom and vertical applications for their clients. This is the core of the program. - **Flagship and enterprise** — complex, high-touch solutions delivered by Topolo or by strategic partners. Deal registration ensures that opportunities a partner sources are protected as the partner's, regardless of engagement model. ## How to get started 1. **Apply** to join the partner program and accept the partner agreement. 2. **Get access** to sandbox tenants, the SDK, and partner documentation. 3. **Complete certification** by building a reference application on the platform. 4. **Deliver your first build** for a client and register the deal. 5. **List and grow** — publish reusable solutions to the catalog and expand your accounts. ## Talk to us To discuss partnership, [contact the Topolo partnerships team](mailto:partners@topolo.app). ## Change Log / Verification - Reverified the program page as the current Docs-owned public commercial summary on 2026-07-30. The page continues to label its terms indicative and defers binding terms to the partner agreement; no code or registry metadata is treated as commercial approval. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. ## Agents and Automation Canonical URL: https://docs.topolo.app/guides/agents-and-automation Clean-room operating guide for Codex, Claude, and headless automation using Topolo OAuth or API keys. ## Clean-room contract Topolo agents do not need Topolo source code or private product knowledge. Public documentation and the credential-scoped application/action catalog are the operational contract. If those surfaces do not publish an endpoint, schema, example, verification step, or recovery path, an agent should report the missing contract instead of guessing. Install the CLI with Node 20 or newer, then install the same skill and MCP integration for Codex and Claude Code: ```bash npm install -g @topolo/cli topolo setup topolo doctor topolo auth login topolo auth status --json topolo whoami --json ``` For a headless process, authenticate with a Topolo API key instead. Keep the key in a secret manager or process environment; do not write it to a repository. `@topolo/cli` owns exact compatible SDK and MCP dependencies. `topolo setup` registers a resolved local Node entry point, so startup does not use `npx`, download code at agent launch, or depend on a separately managed global MCP. The setup command writes only host configuration and the public skill; the MCP reads the same credential as the CLI. For a machine that hosts agents for multiple customer organizations, keep the default registration and add one clearly named registration per context: ```bash topolo context ls --json topolo setup --name topolo-acme --context org:org_acme --env production topolo setup --name topolo-personal-staging --context personal --env staging topolo doctor --name topolo-acme topolo skills status --name topolo-acme --json ``` Replace the example context with an exact value returned by `context ls`. Named setup pins that registration's context and environment without changing the context used by interactive CLI commands. Do not reuse one named agent registration across customer organizations. Doctor reads the pinned context and environment from that exact installed registration, so no shell environment variables are required for verification. Remove a retired customer registration without disturbing the others: ```bash topolo skills uninstall --name topolo-acme --json topolo skills status --name topolo-acme --json ``` ## Public boundary Customer agents may use identity, organization context, credential-scoped applications, resources, workspaces, OAuth, integrations, and published action contracts. They must not use first-party scaffolding, application conformance, Seed, fleet audits, platform credentials, provisioning, deployment, release, or staging operations. Those capabilities live in a separately distributed `topolo-platform` CLI and `topolo-platform` MCP for approved operators only. ## Authentication and authorization OAuth scopes describe what a token can request. Effective access is narrower: it also depends on the active personal or organization context, application grants, action permissions, optional API-key resource bindings, and target-owned runtime policy. An action with `authorizationMode: "runtime"` remains discoverable because its permission depends on concrete input. The target application makes the final decision at invocation time. A 403 is authoritative and should not be retried with guessed fields or another private endpoint. Use `topolo context ls --json` and `topolo context use --json` to change the credential context. Requests cannot override organization identity with a body or query parameter. ## Discover before acting ```bash topolo apps --json topolo services --query web --json topolo actions --service web --json topolo actions capabilities --service web --json topolo actions get app_topolo_web.sites.build --json topolo actions examples app_topolo_web.sites.build --json ``` Application results include `apiKeyResources`, the aliases accepted for resource-scoped credentials and action calls. Action results include exact method/path mapping, input and output JSON Schemas, confirmation policy, and an optional agent contract containing public docs, effects, error recovery, verification, rollback, next actions, and examples. The public [Agent Actions reference](/reference/actions) renders the same published contract without exposing private runtime origins. Every catalog publication is release-gated at 100% for input schema, concrete output schema, effects, expected errors, docs, examples, verification, recovery classification, and the complete agent contract. Derived structural schemas are explicitly marked with `x-topolo-contract-source` and `x-topolo-contract-precision`; agents must not treat structural provenance as field-level semantic precision. Equivalent MCP tools are: | Purpose | MCP tool | | --- | --- | | Identify credential | `topolo_whoami` | | Search applications | `topolo_search_applications` | | Read one application | `topolo_get_application` | | Read resource types | `topolo_get_resource_types` | | List application workspaces | `topolo_list_workspaces` | | Create an authorized workspace | `topolo_create_workspace` | | Rename an authorized workspace | `topolo_rename_workspace` | | Set an authorized default workspace | `topolo_set_default_workspace` | | Search actions | `topolo_search_actions` | | Discover capability actions | `topolo_discover_capabilities` | | Read one action | `topolo_get_action` | | Read examples/docs | `topolo_get_action_examples` | ## Validate and plan Validate exact input locally before any network mutation: ```bash topolo actions validate --data '' --json topolo actions plan --data '' --json ``` `actions plan` returns schema errors, the resolved request, whether confirmation is required/provided, whether the action is executable, verification steps, rollback action, and next actions. It does not execute the action. MCP clients use `topolo_validate_action` and `topolo_plan_action` for the same flow. ## Execute and verify Automatic read-only actions can be called through MCP `topolo_read_action` or the CLI action command without confirmation. A mutation requires explicit approval and `--confirm`: ```bash topolo actions call --data '' --confirm --json ``` Before approval, present the exact action, resolved request, input, resource context, effects, verification, and rollback status from the plan. After execution, perform every published verification step immediately. If verification fails, plan and confirm only the published rollback action; never invent recovery behavior. ## Public API fallback Use `topolo api` only when public documentation provides the exact service, method, path, input, authorization, and verification contract. Catalog actions are preferred because they package these controls into one credential-scoped definition. ## Failure handling - Authentication errors: sign in again, then repeat identity and discovery. - Permission denied: surface the denied permission or runtime policy; do not widen or retry. - Invalid action input: correct the exact reported schema paths. - Confirmation required: plan, obtain approval, then retry once with confirmation. - Unknown action/service: repeat bounded discovery. - Missing schema/docs/examples/verification/recovery: stop the affected operation and report a publication defect. Every call carries a request id. Preserve it when escalating a platform or application failure. ## Change Log / Verification - Reverified the clean-room workflow on 2026-08-14 against `@topolo/cli` 0.8.8, including idempotent `topolo setup`, `topolo doctor`, status, scoped uninstall, Auth-owned identity, and the 20-tool MCP protocol. - Documented the one-package setup/doctor path, multi-organization named registrations, and explicit public versus restricted platform boundary on 2026-08-14. - Published the repository-independent agent workflow on 2026-07-14 with credential-scoped application/resource discovery, action capability discovery, local schema validation, execution planning, explicit confirmation, verification, and rollback guidance for CLI and MCP clients. ## Authentication Canonical URL: https://docs.topolo.app/guides/authentication How authentication and authorization flow through Topolo Auth and downstream services. ## Core model Topolo Auth owns: - user identity - organization membership and role resolution - service registration - service permissions - API key scopes and resource bindings - workspace lifecycle and the caller-specific creation policy for each target application Downstream applications trust Auth for the authorization context they consume. Authentication is not the same as product entitlement. A Topolo account identifies the person; application access can still depend on organization membership, app install state, service grants, app-owned membership, invite activation, free-app policy, or a paid plan. Third-party applications using Topolo for login should create or link their own local account after Auth returns a one-time `sso_code`, then apply their own access and billing rules. For CLI and MCP agents, OAuth scope is also not the final action decision. The credential-scoped application and action catalogs project current service access and permissions, while actions marked `authorizationMode: "runtime"` defer the final decision to the target application for the concrete input and resource. Agents should treat a target 403 as authoritative rather than retrying through an inferred endpoint. The CLI OAuth device-approval page is owned and served by Topolo Auth at the environment's Auth origin. Topolo Developers owns developer application management and OAuth client configuration; it does not own a second device-approval surface. ## Session and access flow 1. A user authenticates with Topolo Auth. 2. Topolo Auth issues the access context used by the client or middleware. 3. Service backends validate the presented credentials with Auth when current role or permission resolution matters. 4. Protected application routes authorize against the resolved service permissions or API key scopes. ## Admin-sensitive behavior Admin-only surfaces such as API key management rely on the current Auth-resolved org role, not just stale token claims. This keeps operator permissions consistent across applications. ## Passkeys Topolo passkeys use WebAuthn with user verification required. Auth owns the one-time registration and authentication challenge state and verifies the browser origin, relying-party identity, authenticator signature, and replay counter before accepting a credential. Applications should use the shared Topolo login and security-management components rather than constructing passkey challenges locally. ## Where to debug Use the internal Auth handbook for current routes, backing tables, and debugging steps when a service appears to disagree about the user role or allowed action. ## Change Log / Verification - Reverified Auth ownership on 2026-08-14 against `@topolo/cli` 0.8.6 and the current Auth/Developers split: device approval is Auth-owned, while Developers manages OAuth clients and developer application configuration. - Clarified OAuth scope versus credential-scoped and target-owned runtime action authorization for clean-room agents on 2026-07-14. - Enabled cryptographically verified WebAuthn registration and assertion handling on 2026-07-12, including single-use server challenge state and clean re-enrollment for credentials created by the retired placeholder verifier. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. - Clarified on 2026-04-21 that Topolo authentication identifies the person while application entitlements and billing can remain app-owned or organization-owned. ## Introduction Canonical URL: https://docs.topolo.app/guides/introduction Overview of the Topolo documentation platform, what is considered canonical, and where to start. ## What this site is TopoloDocs is the canonical documentation application for the Topolo platform. Its public reader is generated from the same checked-in Markdown and JSON corpus used by the authenticated React application, agent manifests, and machine-readable artifacts. ## What is public versus internal - Public docs explain how to build on Topolo, integrate with platform services, and understand the high-level behavior of major applications. - Internal docs add architecture, operational flows, debugging procedures, deployment notes, and agent-oriented implementation detail. - Both builds come from the same source content model so public and internal material stay aligned. ## Where to start 1. Read [Quick Start](/guides/quick-start) for the shortest path into the platform. 2. Read [Authentication](/guides/authentication) for token and session flow. 3. Read [API Keys](/platform/api-keys) if you are integrating across services. 4. Use the [Service Registry](/reference/service-registry) to locate ownership, repos, and app IDs. ## Canonical rules - Topolo Auth is authoritative for service registration, API key scopes, and API key resource catalogs. - TopoloOne is the main operator-facing dashboard for platform controls. - Application teams remain authoritative for their product data models and runtime behavior. - Repo-local docs are source material unless they are explicitly migrated into this docs site. ## Application workspaces Signed-in teams use `/app` to create workspace-owned spaces and documents, maintain immutable versions, localize content, search within the active workspace, and publish public snapshots. Workspace selection, organization access, authentication, navigation, and translations use the same shared Topolo platform contracts as other first-party applications. ## Change Log / Verification - Replaced the Astro runtime with the canonical React, Vite, and TypeScript application architecture on 2026-07-28 while preserving statically generated public, internal, human, and machine documentation routes. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. ## Quick Start Canonical URL: https://docs.topolo.app/guides/quick-start Fast onboarding path for developers integrating with Topolo services. ## Before you start You need Node.js 20 or newer and either an interactive Topolo account or an API key. The CLI, public Docs, and credential-scoped application/action catalog are sufficient on a clean computer; a Topolo source checkout is not required. ## 1. Install and identify yourself ```bash npm install --global @topolo/cli topolo --version topolo auth login topolo setup topolo doctor topolo auth status --json topolo whoami --json ``` `auth login` opens the Topolo authorization flow. The final two commands should return authenticated JSON containing the active identity and context. For a headless process, set `TOPOLO_API_KEY` from a secret manager and run the same status and identity checks. Do not put the key in source control or a command transcript. ## 2. Select the correct context ```bash topolo context ls --json topolo context use personal --json ``` Replace `personal` with an organization context returned by `context ls` when the work belongs to that organization. Context is part of authorization: do not try to override it with an organization id in an action payload. If this computer hosts multiple agent contexts, add a separate pinned MCP registration after selecting the exact context name: ```bash topolo setup --name topolo-acme --context org:org_acme --env production topolo doctor --name topolo-acme topolo skills status --name topolo-acme --json ``` This does not change the interactive CLI context. Use a distinct `topolo-*` name for each customer organization and run the named-registration doctor before handing the registration to an agent host. When that customer context is decommissioned, remove only its named registration and verify that it is gone: ```bash topolo skills uninstall --name topolo-acme --json topolo skills status --name topolo-acme --json ``` Do not uninstall the shared default registration while other agents still use it. ## 3. Discover the service and actions ```bash topolo apps --json topolo services --query web --json topolo actions --service web --json topolo actions capabilities --service web --json ``` Choose an application from the returned catalog, then choose a published action. The action catalog is more precise than a prose route list because it includes the exact endpoint, permission, input and output schemas, confirmation policy, effects, examples, verification, and recovery contract. You can browse the same public contract in [Agent Actions](/reference/actions): enter a service such as `topolo-web`, browse its actions, and select one. Docs never exposes the action's private runtime origin. ## 4. Inspect and validate one exact contract This read-only sequence uses the published TopoloWeb build action as a concrete example: ```bash topolo actions get app_topolo_web.sites.build --json topolo actions examples app_topolo_web.sites.build --json ``` Copy a published example input into `payload.json`, replace example placeholders with your intended values, then validate and plan locally: ```bash topolo actions validate app_topolo_web.sites.build --data @payload.json --json topolo actions plan app_topolo_web.sites.build --data @payload.json --json ``` Validation must succeed before planning. The plan should identify the resolved request, effects, whether confirmation is required, verification steps, and any published rollback action. Planning does not execute the mutation. ## 5. Execute only after approval Read-only actions can execute without mutation confirmation. For a write action, inspect the complete plan and obtain approval before running: ```bash topolo actions call app_topolo_web.sites.build --data @payload.json --confirm --json ``` After the call, perform every verification step returned by the action contract. If verification fails, preserve the request id and use only the published recovery or rollback action; do not guess a private route. ## MCP equivalent `topolo setup` installs the public Topolo skill and registers the exact compatible MCP server bundled with the CLI. Customers install only `@topolo/cli`; no separate MCP or SDK installation is required. The equivalent tool sequence is `topolo_whoami`, `topolo_search_applications`, `topolo_search_actions`, `topolo_get_action`, `topolo_validate_action`, `topolo_plan_action`, and then `topolo_read_action` or `topolo_call_action` as allowed by the contract. The public surface contains identity, organization context, live application and resource discovery, OAuth, and catalog actions. First-party scaffolding, Seed, fleet audits, provisioning, deployment, and release operations are restricted platform tooling and are not customer commands. ## Troubleshooting checkpoints - `auth status` fails: sign in again or replace the expired API key. - An application is absent: verify the active context; discovery is credential-scoped. - An action is absent: search by capability and service before concluding it is unavailable. - Validation fails: change only the reported input paths and validate again. - Planning reports confirmation: stop for approval; do not bypass it. - A 403 is returned: the target runtime denied the concrete request; do not widen scope or retry with guessed identifiers. - Schema, examples, effects, verification, or recovery are missing: report a documentation publication defect and stop the affected operation. ## Change Log / Verification - Updated the clean-machine path on 2026-08-14 to use the single-package `topolo setup` and protocol-level `topolo doctor` flow, documented pinned multi-organization registrations and their status/uninstall lifecycle, corrected the mutation MCP tool name, and documented the customer/platform boundary. Reverified the complete temporary-agent-home lifecycle against `@topolo/cli@0.8.8` and its 20-tool MCP server. - Re-ran the clean-computer workflow against the published CLI/action contract on 2026-07-27 and added explicit success, approval, verification, MCP, and failure checkpoints. - Added the public clean-room CLI/MCP discovery, validation, planning, execution, and verification path on 2026-07-14. ## Third-Party Auth Integration Canonical URL: https://docs.topolo.app/guides/third-party-auth-integration Canonical guide for external developers integrating with Topolo Auth without relying on first-party repo docs. ## What It Is This is the canonical Topolo Auth guide for third-party developers integrating an external application with the Topolo identity service. ## Integration Model Third-party integrations should expect: - Auth hosted at `https://auth.topolo.app` - provisioned app IDs and allowed origins - a service permission catalog and default role bundles defined in Auth before rollout - JWT-based session or bearer-token validation - support for redirect or popup login flows - OAuth and cross-domain SSO entry patterns where applicable - public service login metadata that reflects the auth methods actually available for that service - service-local identities for non-seated portal users where the application owns account membership and Auth owns identity brokerage ## Account And Access Model Topolo Auth is the identity provider. It proves who the person is and returns a one-time OAuth authorization code, or an `sso_code` for SSO/native handoff flows, to the registered application callback. The third-party application remains responsible for its own customer accounts, tenants, plans, trials, invitations, and product access. A user may create a Topolo account during the login flow and still have no access to the third-party application until that application creates or links a local account and applies its own entitlement rules. Do not treat a Topolo identity as proof of subscription, plan status, workspace membership, or app-specific authorization. The expected third-party sequence is: 1. Register the application, callback URLs, scopes, and service metadata in Topolo Developers. 2. Send the user to Topolo Auth for sign-in or signup. 3. Auth shows the consent page at `auth.topolo.app/developer-oauth/consent`, including publisher, callback domain, trust state, and requested scopes, and records approval or denial as an Auth audit event. 4. Receive a one-time authorization code on the registered callback. 5. Exchange the code from the application backend or trusted client path. 6. Create or link the local app account. 7. Decide app access from the app's own free, paid, trial, invite-only, or suspended state. ## Core Flows The supported topics are: - service registration, permission naming, and role-bundle setup - frontend login entrypoints - backend token verification and middleware - token storage and session management - cross-domain SSO - permission and authorization handling - environment configuration - security and troubleshooting guidance - third-party login surfaces that use Auth as an identity broker while keeping customer-account ownership inside the application - service-managed magic-link issuance for external contacts, followed by application-owned invite activation and entitlement checks ## Canonical Rule First-party Topolo applications use the first-party Auth standard documented in the docs platform. This guide exists for external integrations and replaces the old repo-local third-party integration file. The canonical third-party path is: register one service for the application, define the permission catalog, define default role bundles, configure allowed origins and callback/login metadata, use the shared auth client and middleware, then validate tokens with that service context on every backend route. Third-party apps should follow the same enforcement rule as first-party apps: Auth permissions grant access, and any app-local roles, workspaces, projects, or customer-tenancy records may only narrow access inside the product domain. Do not add local `SKIP_AUTH` paths, raw role-string heuristics, or legacy permission aliases alongside the shared Topolo Auth SDK path. When a third-party product owns its own customer-account model, Auth should remain the identity layer only. That means the application may keep customer tenants, memberships, invites, and partner entitlements in its own database while Auth continues to own provider discovery, token issuance, refresh, and any hosted or service-authenticated magic-link flows. Do not create a second Topolo service for a partner area, customer portal, supplier login, or other sub-surface of the same third-party application; those routes use the owning application app id, and the application decides the local account or invite entitlement after Auth proves the identity. Auth supports per-service magic-link delivery ownership: `topolo_managed` lets Auth issue and send the link, while `service_managed` lets Auth issue the one-time link and return it only to the trusted service backend so the application can send mail from its own domain and provider account. Public login surfaces should consume `available_auth_methods` rather than guessing from provider names alone, because Auth may hide a method until the matching provider secrets, service API key, or delivery path actually exists. Installable clients can also declare native callback schemes and exact callback URLs in service metadata so Auth can return one-time `sso_code` callbacks to the native app; the app must redeem the code through `/sso/exchange` and must not accept bearer tokens in callback URLs. Third-party browser applications that want the shared app launcher should consume `AppLauncher` from `@topolo-io/app-launcher` or `TopoloAppShell` from `@topolo-io/app-shell`, pass an in-memory Topolo access token via `getAccessToken`, and leave `storeUrl` on its environment-aware Developers default unless they are targeting a Developers-compatible custom environment. The launcher uses Developers for catalog/search reads and the app-origin Auth gateway for preference, assignment, install, and SSO handoff mutations; third-party apps must not read Auth's internal store catalog directly. Publisher-owned quick links belong in Developers app metadata so the launcher can surface approved app-internal destinations without hardcoded third-party routes. ## Next Steps - Start with `/guides/authentication` for the shared Auth model. - Use `/applications/auth` and the Auth references for the current service and route families. - Coordinate service registration, permission catalog setup, role-bundle setup, and allowed-origin configuration before implementing login flows. ## Change Log / Verification - 2026-07-30: reverified the hosted consent, one-time `sso_code`, service registration, magic-link ownership, and launcher boundaries against exact platform development/staging `62a10749cf1cb14f6e0a80298fdf9f68629a8ed6`. Corrected the launcher package ownership: AppLauncher is exported by `@topolo-io/app-launcher` and TopoloAppShell by `@topolo-io/app-shell`, not by UI Kit. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. - Updated native callback guidance on 2026-04-18 so installable clients use one-time `sso_code` exchange and do not accept bearer-token callback URLs. - Added shared launcher guidance on 2026-04-28 so third-party browser apps use the Developers catalog boundary and shared `@topolo-io/ui-kit` launcher instead of reading Auth catalog APIs directly. - Clarified on 2026-04-23 that partner/customer/supplier sub-surfaces of one third-party app must stay under the owning application app id instead of becoming separate Topolo services. - Clarified the third-party account and access model on 2026-04-21 so Topolo signup creates identity while app-specific entitlements remain owned by the third-party product. - Clarified on 2026-04-21 that browser OAuth consent is hosted by Auth and can be approved by any signed-in Topolo identity, while Topolo Developers owns client registration and review. - Added consent audit guidance on 2026-04-21 so third-party approvals and denials are traceable by client, callback domain, scope set, trust state, and signed-in actor. - Added canonical third-party Auth integration guidance and retired the repo-local guide on 2026-03-30 - Expanded the third-party integration path on 2026-04-10 so external apps now follow the same service-registration, permission-catalog, role-bundle, and shared-client/middleware contract as first-party apps - Added the application-owned customer-account plus Auth-brokered magic-link pattern for third-party login surfaces on 2026-04-11 - Added per-service magic-link delivery ownership guidance on 2026-04-11 so third-party apps can keep email delivery and sender reputation inside their own product boundary - Added guidance for service-declared native callback allowlists on 2026-04-11 so third-party apps can complete brokered sign-in back into native clients without opening the browser admin flow - Clarified the conformance rule on 2026-04-11 so third-party apps now have one supported path: shared Topolo Auth client and middleware, canonical Auth permission grants, and local domain roles only as narrowing controls - Clarified the supported non-seated external-contact pattern on 2026-04-16 for service-local identities, service-managed magic links, and application-owned entitlement checks ## Topolo Admin Canonical URL: https://docs.topolo.app/applications/admin Public overview of the administrative interface used for org, user, service, and audit management across the Topolo platform. ## What It Is Topolo Admin is the operator-facing administrative UI for platform-wide organization, user, service, permission, and audit workflows. ## Architecture The app is a React-based browser surface that depends on Topolo Auth for identity and authorization while presenting role-aware admin workflows for platform-admin and organization-admin users. Legacy Admin routes for developer review queues and support now act only as handoff screens into their owning applications. ## Runtime Surfaces The primary host is `https://admin.topolo.app`. Development and staging mirrors run at `https://admin.topolo.dev` and `https://admin.stg.topolo.us`. ## API Reference Topolo Admin is primarily a UI surface over Auth-backed admin routes. Use `/systems/topolo-admin` together with the Auth references for the current runtime and admin API families. Authenticated admins can set a user password directly from the admin UI without using the public email-token recovery flow. Eligible admins can delete users directly from the admin UI. Standard deletion removes access and hides the user from normal admin reads, while super-admin permanent deletion is reserved for full erase cases. Organization deletion is a soft-delete workflow that immediately suspends org-user access, blocks org-scoped service authorization, and keeps the org available for later restore or retention-based purge. Super admins can also surface deleted organizations in the admin UI and restore them when needed. Org admins can create organization-specific custom roles, start them from an existing org role template, decide which applications belong to each role, and manage each role's per-application permission bundle inside their own organization rather than relying on one fixed global role set for every tenant. Org admins can also manage per-user launchable application access within the set of apps already enabled for the organization. Apps included for the whole org remain enabled for everyone, while seat-based apps can be assigned or unassigned per user only when the org still has available seats. Auth remains the source of truth for seat usage and role-based preset suggestions. Super admins can also manage assignments from the application side by opening a service and assigning or revoking it for selected organizations, every active organization, selected eligible users, or every eligible user. User-level assignment remains bounded by the organization's app entitlement. Organization service assignment separates launchable applications from technical services such as APIs, runtimes, and internal support services using Auth catalog metadata. ## Auth and Permissions Topolo Admin uses Auth-issued bearer or session context and enforces role-based access for platform-admin and org-admin operations. Platform-wide actions are reserved to Auth `platform_super_admin` and `platform_admin` users in the `admin` organization; org-scoped `super_admin` users stay scoped to their own org in the browser UI. Browser login URL construction and callback-code redemption run through the shared Topolo Auth client rather than Admin-owned handoff or exchange paths. That org-scoped tier remains elevated over normal members: same-org owners, org super admins, and admins can still manage organization settings, user security, sessions, and user-level permission workflows without receiving platform-wide controls. The browser keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal reload should return to the Admin workspace rather than appearing signed out while cookie refresh catches up. ## Data Ownership Topolo Admin owns the administrative browser experience. Topolo Auth remains the source of truth for users, orgs, services, permissions, and audit records. That includes per-user application access overrides layered on top of org-level app access. It also includes the app-centric assignment UI; Admin owns target selection and bulk grant/revoke actions while Auth owns persisted organization-service relationships and user-service access evaluation. Developer review queues now live in Topolo Developers, and support workflow now lives in Topolo Support. ## Mobile Experience The checked-in mobile experience contract is **approved** in `web` mode. Its fallback route is `/dashboard`, its offline policy is `undefined`, and it requires organization context. Published permissions: none. - No native routes are published yet. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Admin deploys as a browser application that fronts the centralized Auth admin APIs. ## Failure Modes - stale admin role or session context - UI drift from current Auth admin route families - org-scoped actions incorrectly treated as platform-wide actions ## Debugging Start with `/systems/topolo-admin` for the current host and service metadata, then verify the corresponding Auth admin route family. ## Use It Open [Topolo Admin](https://admin.topolo.app) for the human product surface. The [system handbook](/systems/topolo-admin) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-admin --json topolo actions --service topolo-admin --json topolo actions capabilities --service topolo-admin --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-admin) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Admin and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the web mobile experience contract and its 0 published route(s) against `apps/TopoloAdmin` `origin/staging` `8a54b6ffb422` on 2026-07-27. - Reconciled workspace verification on 2026-06-28 against apps/TopoloAdmin commits through bfa6bfd; reviewed 10 commits since 2026-06-26, including bfa6bfd chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 62cb882 Wait for lazy Admin landing in bootstrap test; 3ca0766 Split Admin startup shell bundle; 9ad7501 Adopt canonical Topolo typography. - Corrected authenticated Admin shell content padding on 2026-04-28 so audit log details and sibling workspace pages use the same tighter spacing from the shared sidebar and top chrome. - Enabled same-tab browser session restore by default on 2026-04-23 so Admin reloads remain signed in after successful Auth handoff or refresh. - Recast Admin onto the explicit platform-role model on 2026-04-24 so only Auth `platform_super_admin` and `platform_admin` users in the `admin` org render platform-admin actions and global datasets. - Restored elevated org-admin handling on 2026-04-24 so same-org owners, org super admins, and admins keep org-scoped settings, security, session, and permission-management access after platform-only UI is removed. - Corrected app-centric assignment management on 2026-04-22 so service rows navigate through the Admin router and assigned organizations or users can be selected for revoke actions. - Segmented organization service assignment by service surface on 2026-04-23 so application access and technical capability access are easier to manage separately. - Added app-centric organization and user assignment management on 2026-04-22. - Delegated Admin login URL construction and callback-code redemption to the shared Topolo Auth client on 2026-04-18. - Re-homed developer review queues and support workflow out of Admin on 2026-04-13 so the old Admin routes now hand operators off to the owning applications instead of fronting duplicate queue logic - Added organization-scoped custom-role management on 2026-04-10 so org admins can create org-specific roles and tailor each role's service permissions inside the admin UI - Clarified org-role bundle management on 2026-04-10 so org admins can explicitly add or remove applications from a role and seed new custom roles from existing org-role templates before tailoring permissions - Converted per-user application access to the seat-assignment model on 2026-04-26 so org admins can assign or unassign seat-based apps inside their own org while org-included apps remain enabled for everyone. - Added per-user application access management on 2026-04-10 so org admins can narrow which org-enabled applications a user can launch and apply role-based preset suggestions from Auth - Corrected the Admin browser favicon rollout on 2026-04-07 so the live application now points at the new brand icon set instead of continuing to rely on the older cached ICO path - Added canonical Topolo Admin coverage and retired repo-local admin docs on 2026-03-30 - Verified the direct admin password-set workflow on 2026-03-31 - Verified the admin user-delete workflow and soft-delete visibility rules on 2026-03-31 - Verified the distinction between soft delete and permanent user purge on 2026-03-31 - Verified that org soft-delete immediately suspends org-user access and hides deleted orgs from normal Admin reads on 2026-03-31 - Verified that super admins can surface and restore soft-deleted organizations on 2026-03-31 - Verified that the Admin add-user form starts with blank email and password fields instead of inheriting login autofill on 2026-04-03 ## Topolo Agent Canonical URL: https://docs.topolo.app/applications/agent Public overview of the Cloudflare-first agent and automation platform in the Topolo portfolio. ## What It Is Topolo Agent is the platform surface for agent execution, workflow orchestration, approvals, inbox work, workspace-linked automation, and standalone reusable person profiles. Agent also owns reusable public assistant surfaces such as Lois on the TopoloOne marketing site, so public chat behavior, persona selection, source links, and safety policy are managed in one place rather than duplicated across websites. ## Architecture The system combines a Cloudflare-backed backend with a browser application and shared packages, using Topolo Auth for login and request validation. Its connector catalog now references the Developers-owned mobile app catalog for installable Android and iOS app metadata instead of a standalone app-library service. Agent-owned person profiles capture source-backed writing style, speaking style, persona rules, usage policy, preview drafts, and optional Voice profile links without automatically creating an autonomous AI worker. The profile manager is a standalone Agent surface and does not depend on Director workflows or workspace-summary hydration. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces See `/systems/topolo-agent` for the current repo and deployment inventory. ## API Reference The current contract is curated rather than OpenAPI-backed in the docs platform. Use `/systems/topolo-agent` and the internal handbook for the active route families and workspace surface. Public website chat integrations call the same Agent-backed public assistant route through their owning site's same-origin proxy. Authenticated products can use `/api/person-profiles` to manage org-scoped profiles, profile sources, style snapshots, and draft previews for downstream script, social, email, chat, and narration generation. The subject user can manage their own likeness profile. Organization owners, admins, and super admins can manage profiles for company use. Normal users cannot manage another human user's likeness profile. ## Auth and Permissions Topolo Agent relies on Topolo Auth for frontend login and backend validation. Workflow, thread, and workspace operations are scoped by the authenticated user and org context. The browser app now uses the shared Topolo browser auth client contract with cookie-backed refresh, callback-code redemption on `auth.topolo.app`, and app identity resolved from the `topolo-agent` Auth service slug at runtime. Browser SSO callbacks delegate Auth `/sso/exchange` handling to the shared client, so callback URLs carry one-time `sso_code` values rather than bearer tokens. The backend worker validates operator bearer tokens through Topolo Auth and does not retain an Agent-local JWT secret verification path. ## Data Ownership Topolo Agent owns threads, workflow state, inbox items, approvals, reports, monitors, workspace-linked execution state, and source-backed person-profile metadata. Topolo Voice owns actual synthetic voice assets, provider voice IDs, and future voice outreach or inbound call-center voice runtime data. Topolo Auth owns the user identity, organization role, and admin boundary used to authorize company use of a human likeness. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/agents`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `agents:read`, `workflows:read`, `reports:read`, `workspace:read`. - `/agents` uses `/api/agents` with the `record.list` template and `agent.agents.list` data source. - `/agents/:id` uses `/api/agents/:id` with the `record.detail` template and `agent.agents.detail` data source. - `/workflows` uses `/api/workflows` with the `record.list` template and `agent.workflows.list` data source. - `/workflows/:id` uses `/api/workflows/:id` with the `record.detail` template and `agent.workflows.detail` data source. - `/approvals` uses `/api/approvals` with the `record.list` template and `agent.approvals.list` data source. - `/approvals/:id` uses `/api/approvals/:id` with the `record.detail` template and `agent.approvals.detail` data source. - `/threads` uses `/api/threads` with the `record.list` template and `agent.threads.list` data source. - `/threads/:id` uses `/api/threads/:id` with the `record.detail` template and `agent.threads.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Agent deploys as a Cloudflare-first application with separate frontend and backend surfaces. ## Failure Modes - workspace or workflow state drifts between frontend and backend - auth service registration is missing or incorrect - agent route contracts change without corresponding docs updates - a normal user can access another user's likeness profile - a product treats a person profile as an autonomous agent without an Auth-linked `agent_employee` principal and accountable human owner ## Debugging Start with `/systems/topolo-agent`, then verify the backend route family and the frontend auth configuration for the failing flow. ## Use It Open [Agent](https://agent.topolo.app) for the human product surface. The [system handbook](/systems/topolo-agent) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-agent --json topolo actions --service topolo-agent --json topolo actions capabilities --service topolo-agent --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-agent) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Agent and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 8 published route(s) against `apps/TopoloAgent` `origin/staging` `5e3fc3d2655a` on 2026-07-27. - Reconciled this page against `apps/TopoloAgent` `origin/staging` `357e53364399` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloAgent commits through 0707d82; reviewed 383 commits since 2026-05-14, including 0707d82 chore(deps): refresh @topolo-io/app-shell pins; d77a50e Stop blocking startup on i18n readiness; db345b8 Fix Agent thread detail header state; 73b7912 Fix Agent navigation error and thread rail UX. - Removed hardcoded concrete app IDs from Agent runtime on 2026-05-13 so browser auth, backend validation, widgets, seed checks, and connector calls resolve service slugs through Auth. - Added standalone person-profile UI and preview-route coverage on 2026-05-08 so Agent can manage and test writing/speaking likeness profiles without requiring another app workflow. - Corrected person-profile authorization on 2026-05-07 so own-likeness and company-admin use are governed by Agent/Auth rather than a separate Consent-style service. - Added public person-profile coverage on 2026-05-07 so Agent is documented as the owner of reusable writing/speaking profile metadata without collapsing it into an autonomous agent. - Moved the Agent mobile app catalog connector to the Developers-owned catalog on 2026-04-22. - Removed the Agent backend local HS256/JWT secret verification path on 2026-04-18 - Delegated Agent browser callback-code redemption to the shared Topolo Auth client on 2026-04-18. - Promoted Agent browser SSO callbacks to Auth `/sso/exchange` on 2026-04-17 so callback URLs require a one-time `sso_code` instead of bearer tokens - Standardized the Topolo Agent browser auth layer on the shared Topolo browser auth client on 2026-03-31 - Standardized the public product label to `Agent`, aligned the frontend launcher/catalog source with Auth-managed metadata, and recorded the frontend Worker target in CloudControl on 2026-04-04 - Added canonical Topolo Agent coverage and retired repo-local product docs on 2026-03-30 ## Topolo Auth Canonical URL: https://docs.topolo.app/applications/auth Public overview of identity, service registration, API keys, and permission ownership across the platform. ## What It Is Topolo Auth is the platform identity and authorization service. It owns user auth, org membership, service registration, permissions, and centralized API key scope catalogs. ## Architecture Auth is a dedicated service with its own worker/runtime surface, D1-backed catalogs, and platform-wide responsibility for validating access context. Its public surface includes interactive login, OAuth and SSO flows, service registration, API-key scope/resource catalogs, machine-oriented auth handoff patterns, Turnstile-protected intake routes used by TopoloOne's public developer funnel, the low-friction developer-workspace signup contract used by `developers.topolo.app`, and the narrow approved-app registration handoff consumed when Developers review approves an application. Internal Developers composition reads page organization application entitlements by app ID and check availability only for that bounded page, keeping launcher authorization work proportional to the requested page rather than the size of the platform catalog. Topolo browser applications standardize on a single cookie-backed refresh contract through the shared browser auth client rather than app-local session refresh implementations. Current-session logout revokes the browser session and makes session-bound bearer tokens fail Auth validation across Topolo apps in that session; multi-device revocation remains a separate logout-everywhere action. Headless JavaScript and TypeScript clients standardize on the same shared auth package for direct credential login and bearer-token validation instead of app-owned Auth protocol code. Auth also mints short-lived surface sessions for global Chat and notification clients. Those sessions carry every organization/workspace context the signed-in user may access, while structured launch grants restore the exact target application and workspace before a notification is acknowledged. ## Runtime Surfaces The primary Auth hostname is `https://auth.topolo.app`. The compatibility account-settings URL at `https://auth.topolo.app/settings` redirects signed-in browser users to Topolo Admin's `/security/user` route, because Auth owns identity APIs while Admin owns the security-settings UI. ## API Reference Use `/reference/api/topolo-auth` and `/reference/apps/topolo-auth` for the current route families and API-oriented contract surface. The canonical docs application now replaces the old repo-local guides for OAuth setup, passkey data management, permission modeling, service APIs, cookie/session behavior, and security troubleshooting. Passkey assertions are not currently accepted as production authentication factors; Auth keeps them out of MFA requirements until full cryptographic WebAuthn verification is available. The current public and admin-adjacent route families also include: - `POST /register` with `developerWorkspace=true` plus `createOrganization=true` for low-friction developer-workspace signup - `POST /api/internal/developer-app-registrations` for the approved-app registration handoff from Topolo Developers into Auth service catalog rows ## Auth and Permissions Auth is the source of truth for app IDs, API key scopes, service permissions, and bindable resource catalogs. Resolved user permissions are published in the canonical `appId.resource:action` shape. First-party and third-party apps should integrate through the shared browser client and middleware packages instead of inventing app-local token parsing or wildcard logic. Those shared clients now default missing role claims to `member` and keep platform roles (`platform_super_admin`, `platform_admin`) distinct from org-scoped roles (`owner`, `super_admin`, `admin`, `member`, `guest`). Authenticated admin inspection of a user's permissions now returns the evaluated permission set plus source breakdowns for org service access, role bundles, and user overrides. Service registrations are only considered complete when permissions, role bundles, API key scopes, and docs coverage are all present. Auth now treats `platform_super_admin`, `platform_admin`, `owner`, `super_admin`, `admin`, `member`, and `guest` as the canonical built-in role ladder. Platform-wide bypass remains limited to `platform_super_admin` and `platform_admin` users in the `admin` organization, while same-org owners, org super admins, and admins retain elevated access only on organization-scoped admin routes such as sessions, security, password reset, and user-permission management. Access-token validation also rehydrates the current stored role and active org context before Auth authorizes those org-scoped admin routes, so recent role changes do not leave browser or CLI calls stuck behind stale JWT claims until the next refresh. Service catalog responses also publish surface classification so clients can distinguish launchable applications from APIs, runtimes, and internal platform services without relying on names or local permission prefixes. The checked-in service manifests now drive production API-key scope rows for drift-sensitive platform and third-party services. Developer workspaces reuse Auth organizations as the canonical owner for private apps and API keys. Topolo Developers owns workspace status, app drafts, public intake, app review, and build-request state; Auth owns identity, central API keys, OAuth clients, service registration, and the approved-app registration handoff. ## Data Ownership Auth owns the canonical API key scope catalog, resource binding catalog, service registration, permission metadata, and the approved-app registration handoff that Topolo Developers consumes after application review. Auth also owns portable exports and deletion for the identity, organization, membership, access, preference, session, and audit records stored in its split databases. Export responses omit authentication and credential secrets. Normal deletion is recoverable soft deletion; permanent deletion is a separate confirmed operation, and scheduled retention purges 30-day soft deletions plus audit records older than 365 days. ## Deployments Auth deploys as a Cloudflare-backed runtime surface with D1-backed data catalogs and route validation. Its cross-origin cookie-backed refresh surface must continue to allow the `X-Topolo-Auth` and `X-App-ID` request headers used by Topolo web applications during session rehydration. That origin policy also needs to cover the first-party Worker custom domains and any retained preview subdomains used by Topolo browser applications, plus the shared `/session/channel` and `/session/broadcast-logout` iframe routes those apps use for logout propagation. ## Failure Modes - stale user or service context - missing service catalog rows for scopes or permissions - mismatched app IDs between docs and Auth seeds - browser apps drift back to custom refresh clients instead of the shared contract - headless or CLI runtimes drift back to app-local Auth login and token-validation clients ## Debugging Start with `/systems/topolo-auth`, then inspect the API and machine artifacts for the relevant service or catalog route. ## Use It Open [Topolo Auth](https://auth.topolo.app) for the human product surface. The [system handbook](/systems/topolo-auth) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-auth --json topolo actions --service topolo-auth --json topolo actions capabilities --service topolo-auth --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-auth) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Auth and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified staging source `2f0298ee46551fdd41acd5378d8f4cb702a8784f` on 2026-08-01: permission-scoped user and organization exports omit password, MFA, invitation, API-key, and OAuth client-secret material; confirmed permanent deletion and bounded retention are implemented; and Auth applies recursive sensitive-data redaction before custom logs are emitted. Disposable organization acceptance proved both post-purge API reads return `404` and no affected split-database rows remain. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. - Replaced the temporary hosted Auth account settings page on 2026-04-19 with a redirect to Topolo Admin `/security/user`, keeping Auth as the identity API owner while Admin remains the security-settings frontend. - Corrected shared Auth client role normalization on 2026-04-24 so browser, headless, and Flutter consumers default missing role claims to `member` and preserve the canonical platform-versus-organization role split. - Corrected Auth access-token validation on 2026-04-24 so org-scoped admin routes rehydrate the current stored role and active context instead of trusting stale JWT role claims until the next refresh. - Corrected public Auth admin-route behavior on 2026-04-24 so same-org owners, admins, and non-`admin`-tenant super admins keep elevated access on org-scoped session, security, password-reset, and user-permission routes while platform-wide bypass stays limited to the Auth `admin` tenant. - Added service surface classification on 2026-04-23 so launcher and admin clients can separate applications from API/runtime/internal services using Auth catalog metadata. - Synced production API-key scope rows for Nexus, Messaging, and third-party services on 2026-04-19 so live D1, generated seed SQL, and manifest permission contracts agree. - Removed the legacy developer registry tables and public/operator developer persistence routes from Auth on 2026-05-21 so Topolo Developers is the only app that persists developer profiles, app submissions, and build requests - Removed the legacy Topolo Developers backend aliases from Auth on 2026-04-15 so `/api/developer-portal/*`, `/api/app-submissions`, and `/api/build-requests` are no longer published from the identity runtime after the Developers ownership cutover - Added the account-first developer-console Auth contract on 2026-04-13 so developer signup can seed an Auth organization workspace, the new `/api/developer-console/*` routes now drive onboarding and private app records, and developer-workspace API-key access is still enforced through the central Auth key model - Added full Topolo developer-platform route coverage on 2026-04-10, including Turnstile-protected TopoloOne public intake, the authenticated `developers.topolo.app` profile/submission/build-request routes, and shared operator review endpoints for developer, submission, and request state - Clarified the public Auth contract on 2026-04-10 so resolved permissions now use the canonical `appId.resource:action` shape and the authenticated inspection surface returns evaluated permissions with source breakdowns - Standardized Topolo browser applications on the shared cookie-refresh auth client on 2026-03-31 - Standardized the JavaScript and TypeScript headless auth contract on the shared Topolo auth client on 2026-03-31 - Verified the cross-origin refresh contract for Topolo web applications, including `X-Topolo-Auth` and `X-App-ID` preflight handling plus first-party Pages/session-channel origin coverage, on 2026-03-31 - Expanded canonical Auth coverage and retired repo-local Auth guides on 2026-03-30 ## Blog Canonical URL: https://docs.topolo.app/applications/blog Write, schedule, publish, and distribute governed articles. ## What It Is Blog is Topolo's governed editorial workspace for article drafts, immutable revisions, publications, media, schedules, and SEO metadata. Sites consume its published article API instead of compiling copies of editorial content into their own repositories. ## Architecture Blog owns editorial truth and publishes headless reads. Consuming sites own presentation rather than maintaining copied article content. ## Runtime Surfaces The browser app is available at `https://blog.topolo.app`, with the editorial workspace under `/articles` and `/articles/:articleId`. ## API Reference Credential-scoped CLI and MCP clients discover typed actions through Topolo Developers for article, publication, media, settings, and privacy workflows. Public publication routes expose published articles by publication key and slug without exposing draft or workspace data. ## Auth and Permissions Editorial browser and API routes use Topolo Auth, the `topolo-blog` service identity, and the selected Topolo workspace. Public routes are read-only and limited to published content. ## Data Ownership Blog owns organization- and workspace-scoped editorial data in D1 and media objects in R2. Scheduled publishing uses its queue and workflow bindings. Authorized organization export and erasure cover the owned editorial records and associated media lifecycle. ## Deployments Production is `https://blog.topolo.app`; staging is `https://blog.stg.topolo.us`; development is `https://blog.topolo.dev`. ## Failure Modes - a scheduled article cannot enter its workflow or publication event queue - a published article references missing media - Developers action or store projections drift from the checked-in manifest ## Debugging Start with `/systems/topolo-blog`, verify the selected workspace and publication, then inspect the returned action error and recovery guidance. ## Use It Discover the service and its current credential-scoped actions before invoking one: ```bash topolo services --query topolo-blog --json topolo actions --service topolo-blog --json topolo actions get app_topolo_blog.articles.list --json ``` ## Change Log / Verification - Added the canonical Blog application, action, storage, privacy, and publication documentation on 2026-08-10. ## Topolo Books Canonical URL: https://docs.topolo.app/applications/books Public overview of Topolo Books in the Topolo application suite. ## What It Is Topolo Books is part of the Topolo business application suite. ## Architecture The application uses the shared Topolo shell and Topolo Auth boundary from the outset. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The scaffold baseline is live at `https://books.topolo.app`. ## API Reference The generated API baseline exposes authenticated workspace routes under `/api/*`, including a native `GET /api/widget` zero-state summary for TopoloOne live workspace, and validates requests through Topolo Auth. ## Auth and Permissions Signed browser and API requests use Topolo Auth through app id `app_0g260hbN8oqv`, supplied to the Worker as `APP_ID` rather than resolved through a runtime Auth slug lookup. ## Data Ownership The generated baseline has no durable domain data yet. Future data must be organization-scoped at the backend boundary. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard/workspace`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`. - `/dashboard/workspace` uses `/api/widget` with the `record.detail` template and `books.workspace.summary` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments The scaffold baseline is live at `https://books.topolo.app`. ## Failure Modes - service registration and app routing can drift while the product is still planned - service slug resolution or deployment Auth-origin metadata can drift while the product is still planned - organization-scoped data models are not implemented until domain work begins ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Books](https://books.topolo.app) for the human product surface. The [system handbook](/systems/topolo-books) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-books --json topolo actions --service topolo-books --json topolo actions capabilities --service topolo-books --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-books) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Books and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 1 published route(s) against `apps/TopoloBooks` `origin/staging` `fb6edfee59b2` on 2026-07-27. - Reconciled this page against `apps/TopoloBooks` `origin/staging` `bbf45497edcc` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloBooks commits through 2fbbd74; reviewed 307 commits since 2026-05-14, including 2fbbd74 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); db5e901 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 8a96b1f Stop blocking startup on i18n readiness; cf943dc Adopt canonical Topolo typography. - Centralized runtime app identity on 2026-05-13 so Books uses provisioned app id `app_0g260hbN8oqv` without runtime slug lookup. - Added the scaffold Books `GET /api/widget` summary on 2026-04-26 for TopoloOne live workspace. - Deployed Worker/static-assets baseline to `https://books.topolo.app` on 2026-04-23. - Scaffold generated on 2026-04-23 from `topolo apps scaffold`. ## Topolo Brand Canonical URL: https://docs.topolo.app/applications/brand Canonical versioned identity, voice, claims, CTA, and creative asset governance for Topolo applications. ## What It Is Topolo Brand is the canonical source for reusable brand identity across Topolo applications. A brand kit combines visual tokens, approved assets, voice rules, claims, qualifiers, calls to action, accessibility requirements, and legal restrictions. ## Architecture Topolo Brand separates mutable editorial drafts from immutable published snapshots. The control database also persists one Brand workspace per organization so the shared workspace switcher uses a real authorized resource. Four concern-owned D1 databases store workspace and kit control, versioned content, asset metadata, and append-only audit events. R2 stores the governed asset bytes. Consumer applications resolve published snapshots through authenticated service bindings. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces - `brand.topolo.app` provides the production editor and governance surface. - `brand.stg.topolo.us` provides staging verification. - `brand.topolo.dev` provides the isolated development surface. - The Brand API provides kit, version, asset, binding, resolution, and validation routes. ## API Reference The API supports kit editing, version publication, governed asset registration and upload, application-resource bindings, published-version resolution, and final-content validation. Consumer applications use read-only resolution, validation, and asset-content routes. Publication returns `422 brand_version_not_publishable` with structured issues when the draft has no primary logo, references a missing or wrong-kind logo/font asset, or violates its own required foreground or primary contrast. Resolution expands stored app-relative asset paths against the serving environment so consumers always receive fetchable absolute URLs. ## Versioned Brand Truth Editors work in a mutable draft. Publishing atomically retires the prior published snapshot and publishes the selected draft inside the content database. The API derives the active version from that authoritative content state rather than maintaining a cross-database pointer. Consumer applications resolve and store the exact version ID, so updating a brand never silently changes an existing Social Studio project or obscures which rules Socialize used to generate an asset. ## Claims And CTAs Claims carry an explicit lifecycle: draft, approved, restricted, or retired. They can also carry sources, required qualifiers, regions, channels, and validity windows. Social generation may use only approved claims that are valid for the requested channel. Calls to action are managed in the same kit. Socialize can select an approved channel-compatible CTA and validate the final output against the same immutable snapshot. ## Creative Assets Logos, fonts, imagery, icons, motion, audio, and templates are stored as governed brand assets. Every asset records its media type, license context, and accessibility text where required. The Visual workbench uploads logo assets and assigns primary, reversed, and mark roles from the version's actual asset set; a draft may be incomplete, but publishing requires a valid primary logo. ## Application Bindings Topolo Brand binds one brand kit to an application-owned resource. Socialize resolves the kit for a Socialize brand; Social Studio resolves it for a Studio workspace. Consumers receive read-only published versions and cannot mutate the canonical brand definition. ## Auth and Permissions People authenticate with Topolo Auth and require Brand read or write permissions. Auth synchronizes the organization's persisted Brand workspace and the shared shell selects only an authorized workspace ID. Application consumers authenticate as allow-listed Topolo services and receive read-only access scoped to the organization and bound resource. ## Data Ownership Topolo Brand owns kit drafts, immutable versions, governed asset metadata and bytes, claims, CTAs, and consumer bindings. Socialize retains ownership of social brands and posts; Social Studio retains ownership of workspaces and compositions. ## Privacy Lifecycle Authenticated users can export every Brand record owned by the selected workspace and can erase that workspace's app-owned records and governed asset bytes through confirmed actions. A daily retention job pseudonymizes expired identity fields and removes archived asset metadata and R2 bytes after their declared horizon. These operations remain scoped to the exact organization and Brand workspace; deleting one workspace does not affect another workspace's kits or assets. ## Deployments Brand is deployed before its consumers. A usable environment requires the Brand API and web surface, control/content/assets/audit D1 migrations, R2 object storage, Auth workspace-resource synchronization, at least one published kit, and bindings for each consumer resource. The public marketplace entry is owned by `app_topolo_brand`, categorized under **Delivery & Operations / Brand & Marketing**, and carries the same governed description, shared catalog-generated Brand icon, price, and 24-action contract in the current staging source. ## Safety Boundary Brand validation rejects unapproved or channel-restricted claims, missing required qualifiers, banned language, invalid CTAs, unknown or wrong-kind asset references, and required palette contrast failures. Warnings such as a decorative accent below the declared minimum or an unused image without alt text remain visible without blocking publication. A published kit is a governance input, not permission for a consumer application to bypass its normal authorization or publishing review. ## Failure Modes Resolution fails closed when a resource is unbound, a kit has no published version, the caller is not authorized, or a required asset is unavailable. Publication fails with structured remediation when logo/font references or mandatory contrast are invalid. Validation returns explicit errors for claim, qualifier, CTA, language, asset, and snapshot-governance violations. ## Debugging Confirm the organization and consumer resource binding first, then inspect the resolved version ID and asset readiness. For publication refusal, follow the returned issue paths under `visual.logos`, `visual.typography`, or `visual.palette`; confirm the selected IDs exist in the version's own `assets`. If a consumer cannot fetch an asset, confirm resolve returned an absolute URL for the current Brand environment. Generation records should retain the exact version ID so the governing snapshot can be reproduced. ## Use It Open [Topolo Brand](https://brand.topolo.app) for the human product surface. The [system handbook](/systems/topolo-brand) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-brand --json topolo actions --service topolo-brand --json topolo actions capabilities --service topolo-brand --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-brand) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Brand and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled logo editing, asset URL portability, and publication governance against Brand staging source `abd31ec9a88d` on 2026-07-31. The Visual workbench now assigns real uploaded logo assets; drafts accept app-relative asset paths; resolve expands them per environment; and publication blocks missing/wrong-kind asset references plus mandatory foreground/primary contrast failures with structured `422` issues. - Reconciled this page against exact Brand development/staging `253c651cfcedac77721f5719635644d42db6c2d6` on 2026-07-30. Added the implemented export, erasure, daily retention, pseudonymization, and governed R2 deletion boundary; corrected the published action count from 19 to 24. Exact staging API `9e999e10-6f7a-43b5-a809-e8a348037e54` and web `a77726f0-66f8-4aa5-83b1-f053b3dadb77` are healthy, and the live canary proved scoped retention/erasure without changing the existing default workspace. - Reconciled this page against `apps/TopoloBrand` `origin/staging` `159b05ec5865` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - 2026-07-17: documented persisted Brand workspaces, Auth resource synchronization, and the shared catalog-owned application icon. - 2026-07-16: documented canonical development, staging, and production provisioning plus the shared marketplace and action contract. - 2026-07-15: documented the concern-split control/content/assets/audit storage topology and authoritative content-owned publication state. - 2026-07-15: documented the canonical Brand boundary, immutable version contract, governed assets, read-only consumer model, and validation behavior. ## Topolo BugFix Canonical URL: https://docs.topolo.app/applications/bugfix Public overview of BugFix, including AI-assisted bug analysis, fix generation, and Nexus-backed provider usage. ## What It Is Topolo BugFix is the bug analysis and fix-automation application in the Topolo portfolio. It accepts bug reports, generates candidate fixes with AI, and can open pull requests for human review. ## Architecture BugFix runs as a worker-backed application with D1 persistence for reports, fixes, validations, and pull-request metadata. AI generation now routes through Nexus rather than calling Anthropic or OpenAI directly from the BugFix worker. ## Runtime Surfaces - BugFix worker API - D1-backed bug, fix, validation, and PR data - Nexus gateway for AI provider access - GitHub for branch and PR automation ## API Surface Primary route families include: - `/api/reports` - `/api/fixes` - `/api/admin/queue` - `/webhooks/github` - `/webhooks/validation` ## API Reference BugFix currently uses curated route coverage rather than a published OpenAPI surface in `system-apps/TopoloDocs`. ## AI Generation BugFix uses Nexus for AI-backed fix generation and validation. Product-specific prompt logic, JSON parsing, confidence handling, and GitHub workflows remain local to BugFix, while provider invocation and usage attribution move through Nexus. ## Auth and Permissions Authenticated review and generation paths use user auth. Platform-wide BugFix admin access is reserved for Auth users whose role is `super_admin` in the `admin` organization. Background or auto-triggered AI flows use trusted service-context calls into Nexus with explicit organization and optional user attribution. ## Data Ownership Topolo Auth owns workspace identity and accessible-workspace listing. BugFix keeps an identity-only workspace mirror to scope its report rows, and owns bug reports, generated fixes, validations, and PR workflow state. Nexus owns provider access and usage attribution. ## Deployments BugFix deploys as a Cloudflare Worker. AI generation depends on Nexus gateway reachability plus a trusted Nexus service token for server-side attribution flows. Canonical gateway hosts are `https://nexus.topolo.dev` in development, `https://nexus.stg.topolo.us` in staging, and `https://nexus.topolo.app` in production. ## Failure Modes - report has no organization context for Nexus attribution - Nexus service token or gateway configuration is missing - provider failure prevents fix generation or validation - GitHub PR creation succeeds or fails independently of AI generation ## Debugging - confirm BugFix can reach Nexus and has a valid service token - verify bug reports include `org_id` for auto-triggered AI generation - inspect Nexus usage logs before checking provider dashboards - inspect BugFix report and fix statuses if generation fails mid-flow ## Use It Open [Improve Topolo](https://bugfix.topolo.app) for the human product surface. The [system handbook](/systems/topolo-bugfix) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-bugfix --json topolo actions --service topolo-bugfix --json topolo actions capabilities --service topolo-bugfix --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-bugfix) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Improve Topolo and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the Auth-owned workspace identity mirror and current Worker deployment source through `system-apps/TopoloBugFix` `origin/staging` `53e9ed22c4be` on 2026-07-29; no app-local workspace lifecycle remains. - Reconciled workspace verification on 2026-06-27 against system-apps/TopoloBugFix commits through 959cc6e; reviewed 133 commits since 2026-05-14, including 959cc6e Bump shared shell and onboarding packages; 20ec69d chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); fe48c2f fix(bugfix): align root wrangler split D1 bindings; 623f481 Prepare BugFix copy for translation. - Restricted BugFix platform-wide admin recognition to Auth `super_admin` users in the `admin` organization on 2026-04-23. - Verified against the current Nexus-backed BugFix generation flow on 2026-03-29 ## Topolo Bytes Canonical URL: https://docs.topolo.app/applications/bytes Public overview of the media-management and sharing surface built around Cloudflare edge storage and media tooling. ## What It Is Topolo Bytes is the media and asset-management surface in the Topolo portfolio. It manages uploads, organization, sharing, and guest-friendly access flows over Cloudflare-backed storage. ## Architecture Bytes combines a browser interface with a worker/API surface and Cloudflare storage primitives such as R2 and KV. It also exposes guest-sharing and media-processing workflows. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces Use `/systems/topolo-bytes` for the current deployment inventory and service metadata. ## API Reference The contract is currently curated in the docs platform rather than OpenAPI-backed. The active surface centers on asset listing, upload, organization, sharing, and media-processing workflows. ## Auth and Permissions Authenticated operator flows rely on Topolo Auth. Guest collection views are a distinct sharing surface and should be treated separately from operator access. The operator browser session path now uses the shared Topolo cookie-refresh auth client. Browser SSO callbacks delegate Auth `/sso/exchange` handling to the shared Auth client, so callback URLs carry one-time `sso_code` values rather than bearer tokens. Callback completion stays inside the SPA so the memory-only access token can hydrate the protected media workspace. Bytes does not expose a legacy `/sso?token=` browser handoff route. The operator API now requires Topolo Auth validation for bearer tokens and does not retain a Bytes-local JWT secret or development auth bypass path. Bytes resolves its concrete Auth app id at runtime from the canonical `topolo-bytes` service slug rather than embedding environment-specific app ids in browser or Worker code. Platform-wide Bytes operator access is reserved for Auth users whose role is `super_admin` in the `admin` organization. ## Data Ownership Bytes owns asset metadata, folder organization, sharing links, and media-processing state while depending on Cloudflare storage bindings for object persistence. ## Mobile Experience The checked-in mobile experience contract is **published** in `native_capability` mode. Its fallback route is `/files`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `files:read`, `sharing:read`. - `/files` uses `/api/list` with the `record.list` template and `bytes.files.list` data source. - `/shares` uses `/api/shares` with the `record.list` template and `bytes.shares.list` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Bytes deploys as a Cloudflare worker plus browser app pair with storage and sharing bindings. ## Failure Modes - guest-sharing behavior drifts from operator permission rules - storage bindings or sharing namespaces are misconfigured - auth assumptions leak into guest-only access paths ## Debugging Start with `/systems/topolo-bytes` and the worker `/health` endpoint, then verify whether the issue belongs to storage, guest sharing, auth, or media-processing flows. ## Use It Open [Bytes](https://bytes.topolo.app) for the human product surface. The [system handbook](/systems/topolo-bytes) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-bytes --json topolo actions --service topolo-bytes --json topolo actions capabilities --service topolo-bytes --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-bytes) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Bytes and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloBytes` `origin/staging` `cbca40ebd3da` on 2026-07-27. - Reconciled this page against `apps/TopoloBytes` `origin/staging` `a5c9472232fa` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Removed retired debug media-processing surfaces and enforced privacy-safe structured worker logging at staging commit `bed31076` on 2026-07-22. - Reconciled workspace verification on 2026-06-28 against apps/TopoloBytes commits through ca61087; reviewed 447 commits since 2026-05-14, including ca61087 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 34606f2 Split Bytes startup root bundle; b4b82fc Adopt canonical Topolo typography; 3bf31d1 Remove Bytes topbar app navigation. - Added the Bytes worker public `/health` endpoint on 2026-04-29 for staging and deployment probes. - Removed hard-coded concrete Bytes app ids from the browser and Worker runtime on 2026-05-13; Bytes now resolves app identity through Auth service-slug lookup. - Restricted Bytes platform-wide operator recognition to Auth `super_admin` users in the `admin` organization on 2026-04-23. - Deferred closed Bytes lazy panels and modals on 2026-04-21 so the signed-in media browser reaches a usable workspace without mounting hidden panel loaders during startup. - Corrected the Bytes post-callback SPA navigation on 2026-04-20 so successful handoff reaches the media workspace without losing the memory-only Auth token. - Removed the remaining Bytes worker-local JWT secret handoff and unused development auth bypass on 2026-04-18 - Promoted Bytes browser SSO callbacks to Auth `/sso/exchange` on 2026-04-17 so callback URLs require a one-time `sso_code` instead of bearer tokens - Delegated Bytes browser callback exchange to the shared Auth client on 2026-04-18 and removed the legacy `/sso?token=` browser route - Standardized Topolo Bytes browser auth on the shared Topolo auth client on 2026-03-31 - Standardized the public product label to `Bytes`, aligned the frontend launcher/catalog source with Auth-managed metadata, and removed stale CloudControl placeholder frontend targets on 2026-04-04 - Added canonical Topolo Bytes coverage and retired repo-local media-manager docs on 2026-03-30 ## Topolo Calendar Canonical URL: https://docs.topolo.app/applications/calendar Public overview of the scheduling and booking application — shareable event types, availability, invitations, and calendar-safe booking lifecycle controls. ## What It Is Topolo Calendar is the scheduling application for public booking pages, availability management, invitations, and booking lifecycle controls across the Topolo platform. Hosts publish event types at `calendar.topolo.app//` and invitees book timeslots without needing an account. ## Architecture Calendar is a Cloudflare-native Worker with D1 as the system of record and a per-host Durable Object (`CalendarHostDO`) acting as the hot-path coordinator. The DO serialises booking attempts, writes slot holds through to D1, caches availability windows, and writes confirmed bookings to D1 before acknowledging success. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The primary public surface is `https://calendar.topolo.app`. The root page renders Topolo's shared landing page from Auth-managed Calendar landing config. Public booking pages live at `//`. The authenticated admin UI is served from `/app` inside Topolo's shared application shell, with the app switcher preloaded during shell boot and a weekly Calendar workspace as the default signed-in view. ## API Reference The public booking API exposes host lookup, event-type lookup, availability probing, booking holds, booking confirmation, and token-backed invitee manage links under `/api/public/*`. The authenticated host-management API lives under `/api/admin/*` for host profile, event type, availability rules and overrides, booking detail/edit/reschedule/cancel/resend actions, and external-calendar free/busy sync scaffolding. ## Auth and Permissions Calendar uses Topolo Auth for workspace access through the stable service slug `topolo-calendar`; the Worker and browser resolve the current environment's concrete Auth app id before login, callback exchange, widget responses, and admin Auth middleware checks. Public booking endpoints are unauthenticated so invitees can load a page, probe availability, place a temporary hold, and submit a booking. Admin endpoints (`/api/admin/*`) require a valid bearer token through the shared Auth middleware and enforce the matching Calendar service-scoped permissions for host, event type, availability, and booking actions. Calendar's admin sign-in uses the shared first-party Topolo login page on `calendar.topolo.app/login`, with embedded email/password sign-in, password reveal, signup handoff, Auth-backed password submission, and `/auth/callback` completion. After first sign-in, users without a Calendar host profile complete the shared `@topolo-io/onboarding` first-run flow to choose their booking handle, display name, and timezone before the admin dashboard opens. Public invitee booking flows remain account-free. ## Data Ownership Calendar owns hosts, event types, availability rules and overrides, bookings, attendees, delivery receipts, persisted slot holds, recurrence series, public manage-token hashes, external-calendar sync projections, stable Nexus connection references, and imported external busy blocks. Nexus is the sole owner of Google, Microsoft, and CalDAV provider identity, lifecycle state, errors, scopes, expiry, and credentials under `app_topolo_calendar`; Calendar resolves the connection only while connecting or syncing and does not persist provider credentials in D1. Meeting sessions (join tokens, transcripts, realtime state) remain owned by Topolo Chat; Calendar stores a `meetingProviderRef` pointing at the created Chat meeting for Topolo Chat event types. External providers (Microsoft Teams, Google Meet, Zoom) remain configurable per event type by storing the host-supplied meeting link or instructions on the booking until native provider adapters are connected. ## Invitations and Manage Links Calendar emits `calendar.booking.invite_requested`, `calendar.booking.updated`, `calendar.booking.cancelled`, and `calendar.booking.reminder_due` events through TopoloNotify after booking persistence succeeds. The notification payload includes a Calendar-built RFC5545 `.ics` attachment with stable `UID`, incrementing `SEQUENCE`, `METHOD:REQUEST` for create/update/reminder, and `METHOD:CANCEL` for cancellation. Invitees receive token-backed manage links at `/manage/` for view, cancel, and reschedule without a Topolo account. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/agenda`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `bookings:read`, `bookings:write`. - `/agenda` uses `/api/admin/bookings` with the `calendar.agenda` template and `calendar.agenda.list` data source. - `/agenda/:id` uses `/api/admin/bookings/:id` with the `record.detail` template and `calendar.agenda.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Calendar deploys as the Cloudflare Worker `topolo-calendar` with static assets bound through `ASSETS`, a D1 binding named `DB`, and the `CALENDAR_HOST` Durable Object binding. The production domain is `calendar.topolo.app`; staging mirrors it at `calendar.stg.topolo.us` with a staging-specific browser build so Auth and app-origin calls stay inside the staging installation. ## Recurrence and Sync Scope Calendar supports a bounded RFC5545 recurrence subset for daily, weekly, and monthly series with interval plus count or until limits. The Worker materializes occurrences for the next 18 months and records edited or cancelled occurrence exceptions. External calendar sync is provider-neutral at the core: Google Calendar, Microsoft Graph, and CalDAV adapters import free/busy blocks into `external_busy_blocks`, and the same conflict engine checks confirmed bookings, persisted holds, availability overrides, and external busy blocks. ## Failure Modes - Google/Microsoft OAuth and CalDAV sync require an active Nexus connection under `app_topolo_calendar`; missing, disconnected, deauthorized, deleted, or error-state connections fail closed - rows migrated from Calendar's retired local credential store have no canonical Nexus reference and remain disconnected until the host reconnects the provider - invitee manage links are bearer tokens; stale or rotated links return `invalid_or_stale_token` - `TOPOLO_NOTIFY_URL` or `TOPOLO_SERVICE_CLIENT_SECRET` missing prevents invite/update/cancel/reminder delivery while leaving booking persistence intact ## Debugging Start with `/systems/topolo-calendar`, then verify the `DB` and `CALENDAR_HOST` bindings. Public 4xx responses usually mean a missing host, missing event type, malformed JSON payload, unavailable slot, or expired hold. Admin 401 responses should be traced through Topolo Auth validation for the app id resolved from `topolo-calendar`. ## Use It Open [Calendar](https://calendar.topolo.app) for the human product surface. The [system handbook](/systems/topolo-calendar) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-calendar --json topolo actions --service topolo-calendar --json topolo actions capabilities --service topolo-calendar --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-calendar) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Calendar and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Completed the approved Calendar staging protection proof at exact source `4e5380c0ddaf5909184891cbbff9d07b189ea33c`, API version `fe115b97-773d-49e4-bef3-1c1d79a74afb`, and web version `d3f38b3c-48b1-411b-8427-1f5e4d43bcc1` on 2026-08-03. Restricted scheduling data uses versioned application-layer encryption and purpose-bound keyed hashes. Dry-run, real, and repeat migration passes reported zero remaining plaintext; the baseline canary reported 54 protected fields with zero failures/plaintext. A synthetic host, external calendar, and busy block round-tripped through the published action surface while the canary remained clean; cleanup returned the final canary to 54 protected fields with zero failures/plaintext. Production promotion remains separately authorized. - Removed the stale action-coverage exclusion for Calendar's retired credential-convergence route at staging commit `2ab76973224b` on 2026-08-01. The exact source audit now classifies all 48 served routes with zero gaps, dead actions, or invalid exclusions; staging API version `93de2cb8-d952-4ab2-9434-b85542f615d5` and web version `5196315c-ca71-47e7-b96b-83094ed6f29b` passed the governed deployment. - Reconciled canonical Nexus connection ownership against `apps/TopoloCalendar` staging commits `7d76370d7cf3`, `4b2c7d6a3cef`, and `c49a36029ad2` on 2026-08-01. Calendar now retains only scheduling/sync projection state and a stable Nexus connection reference; Nexus owns provider identity, lifecycle, errors, scopes, expiry, and credentials, and the retired Calendar credential-store binding and re-encryption path are absent from the canonical manifest and runtime configuration. - Retired Calendar's 2026-07-28 app-local credential protection and convergence path when canonical Nexus connection ownership landed on 2026-08-01; no compatibility route or credential-store binding remains. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloCalendar` `origin/staging` `aca56ed07338` on 2026-07-27. - Reconciled this page against `apps/TopoloCalendar` `origin/staging` `8f12c0d80378` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloCalendar commits through 15b439e; reviewed 278 commits since 2026-06-01, including 15b439e chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); a2444d0 Adopt canonical Topolo typography; df2793d Split Calendar shell startup bundle; 22fa5bc Lazy load Calendar routes. - Resolved Calendar app identity from the Auth-owned `topolo-calendar` service slug on 2026-05-13 so the browser login/callback path, Worker widget payload, and admin Auth middleware no longer carry checked-in concrete `app_*` ids. - Moved Google/Microsoft Calendar OAuth app client credentials out of Calendar Worker secrets and into Nexus generic integration app credentials on 2026-06-01. - Added calendar invite/update/cancel/reminder Notify events, Calendar-owned ICS generation, public manage links, admin booking lifecycle actions, availability overrides, recurrence materialization, persisted holds, and native Google/Microsoft/CalDAV free/busy sync on 2026-06-01. - Verified Calendar staging origin isolation on 2026-04-30. - Added configurable meeting providers on 2026-04-26: Topolo Chat event types now create Chat guest meeting links at booking confirmation, while Teams, Google Meet, and Zoom event types can carry host-supplied links or instructions. - Replaced the signed Calendar admin page with the shared Topolo shell and default weekly Calendar workspace on 2026-04-22, including the preloaded app switcher and authenticated bookings list route. - Replaced Calendar's local first-run host setup form with the shared `@topolo-io/onboarding` shell and flow on 2026-04-22. - Fixed Calendar admin permission checks on 2026-04-22 so Auth's service-scoped Calendar grants unlock the admin API after sign-in. - Replaced Calendar's local root marketing screen with the shared landing page and registered Calendar as a first-party UI Kit app on 2026-04-22 so the deployed `/login` route exposes embedded email/password sign-in instead of the external-app provider-only prompt. - Moved Calendar admin sign-in onto the shared app-origin first-party login surface on 2026-04-21 and seeded Auth plus Developers D1 so Calendar is a Topolo-owned platform app under the Topolo organization. - Added canonical Calendar system coverage and aligned the public handbook with the current Worker, D1, Durable Object, and Auth contract on 2026-04-21. - Enforced Calendar admin route permissions and provisioned the production D1 binding on 2026-04-21. ## Topolo Campaigns Canonical URL: https://docs.topolo.app/applications/campaigns Campaign codes, offers, distribution batches, placements, and cross-app customer journeys. ## What It Is Topolo Campaigns coordinates measurable campaigns that connect physical or digital codes to offers and customer journeys. It keeps campaign batches, code placements, engagement events, and redemptions together while linking to resources owned by other Topolo applications. ## Architecture The application uses the shared Topolo landing page, shared login page, auth callback handling, and shared Topolo shell from the outset. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The planned production host is `https://campaigns.topolo.app`, with public entry at `/`, sign-in at `/login`, and callback completion at `/auth/callback`. ## API Reference The authenticated API exposes Campaigns workspaces, offers, campaigns, code batches, placements, journey events, redemptions, dashboards, and typed links to app-local resources. Its action catalog is discoverable by Topolo CLI and MCP clients with the permissions of the current credential. ## Auth and Permissions Signed browser and API requests use Topolo Auth through the `topolo-campaigns` service slug. Organizations can grant access to selected Campaigns workspaces, including simultaneous access to several resources where the client supports it. ## Data Ownership Campaigns owns its own organization- and workspace-scoped records. Quro series, Web sites, Forms forms, CRM workspaces, Chat channels, Calendar event types, and Notify events remain owned by their respective applications and are connected by explicit resource links rather than a universal workspace ID. ## Deployments The planned production host is `https://campaigns.topolo.app`. Staging mirrors the scaffold at `https://campaigns.stg.topolo.us`. ## Failure Modes - service registration and app routing can drift while the product is still planned - a linked resource is removed in its owning application without updating the Campaigns integration ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Campaigns](https://campaigns.topolo.app) for the human product surface. The [system handbook](/systems/topolo-campaigns) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-campaigns --json topolo actions --service topolo-campaigns --json topolo actions capabilities --service topolo-campaigns --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-campaigns) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Campaigns and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled this page against `apps/TopoloCampaigns` `origin/staging` `7097990bc15e` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Added workspace-scoped orchestration and credential-discoverable actions on 2026-07-14. - Scaffold generated on 2026-07-13; first-party scaffolding now uses restricted `topolo-platform apps scaffold`. ## Application Catalog Canonical URL: https://docs.topolo.app/applications/catalog Platform-wide inventory of the Topolo application portfolio and where each product currently stands in docs coverage. ## Why this page exists Topolo is not a four-application platform. The repository contains a much broader portfolio of products, platform surfaces, and legacy-to-modern transitions. This page marks the application catalog as a first-class public surface. ## Portfolio shape The current public-facing portfolio represented in this docs site includes: - platform and admin surfaces such as Topolo Auth, TopoloOne, and Topolo Admin - customer-facing applications such as Socialize, CRM, Forecast, Roadmapper, Pay, Quro, Chat, Calendar, Messages, Mail, Commerce, and Web - device and operations clusters such as TopoloMDM and Topolo Device Platform - supporting product lines such as Topolo Social Studio, Topolo Bytes, Brand, Agent, and Developers ## Documentation coverage - Canonical public and internal app pages now exist for the primary first-party product surfaces tracked in the platform inventory. - TopoloMessages is the first-party cross-app mailbox and delivery surface; TopoloMail owns email product workflows, while channel-specific messaging remains documented by its owning application. - Generated OpenAPI reference currently exists where applicable, including Socialize and TopoloCRM. - The system registry remains the fastest inventory view for runtime hosts, app IDs, and ownership metadata across the full portfolio. ## Current source-of-truth rule `system-apps/TopoloDocs` is the source of truth for product and platform behavior. Repo-local READMEs and handoff docs are no longer treated as fallback contract sources for first-party systems. ## Change Log / Verification - Reverified the canonical 51-repository, 64-system fleet inventory on 2026-07-30. Removed retired/ambiguous Showcase, Messaging, and duplicate Studio labels from the portfolio summary; current machine inventory and per-system pages remain the authority for exact app IDs, hosts, ownership, and lifecycle. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. ## Topolo Chat Canonical URL: https://docs.topolo.app/applications/chat Public overview of the collaboration surface for channels, direct messages, meetings, guests, and remote-assist workflows. ## What It Is Topolo Chat is the collaboration application for channels, direct messages, meetings, guest access, transcripts, future remote-assist workflows, and the shared cross-app Chat widget used by eligible Topolo apps. ## Architecture Chat combines a Cloudflare-native backend, a web client, realtime and meeting bindings, and optional desktop and mobile shells. Cross-app HTTP policy is owned by the shared Worker runtime: Chat no longer adds permissive wildcard CORS headers itself. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The primary public surface is `https://chat.topolo.app`; staging mirrors it at `https://chat.stg.topolo.us` with a staging-specific browser build so Auth and app-origin calls stay inside the staging installation. Assigned users can also access Chat through the shared `@topolo-io/app-shell` bottom-right widget, which mounts only after Auth confirms the `topolo-chat` service is assigned. The widget preserves lightweight UI continuity across first-party app switches while message data remains owned by Chat. ## API Reference The current contract is curated in the docs platform and centers on channels, DMs, uploads, meetings, guests, notifications, notes, audit events, remote-assist transport, and compact widget endpoints under `/api/widget/chat`. Shared CORS handling reflects an allowed first-party origin and the requested canonical resource headers, including `X-Topolo-Resource-ID` and `X-Topolo-Resource-Type`, for widget preflight and authenticated responses. ## Auth and Permissions Topolo Chat uses Topolo Auth for organization-scoped workspace access. Protected workspace bearer-token requests validate through Auth and do not accept locally decoded JWT claims from a Worker secret. Browser login handoff, SSO callback-code redemption, and returning-user cookie hydration delegate to the shared Topolo Auth client after Chat resolves the Auth-owned `topolo-chat` service slug at runtime, while guest meeting entry remains intentionally separate from normal workspace membership. Workspace-admin paths such as API key management now require explicit Chat service permissions instead of relying on local role-name heuristics. For first-party Topolo users, `/login` renders Chat's branded shared LoginPage directly in the Chat shell. Hosted Auth login pages are reserved for third-party/provider handoff, not the default credential form. ## Data Ownership Chat owns organization-scoped workspace, membership, channel, DM, message, upload, meeting, guest, transcript, audit, remote-assist session state, and the runtime projection of Agent personas used by the cross-app widget. Its bootstrap API returns `organization`, `organizationPolicies`, and `organizationMembers` as the canonical tenant payload keys. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/threads`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `chat.threads.read`, `chat.messages.write`. - `/threads` uses `/api/channels` with the `chat.threadList` template and `chat.threads.list` data source. - `/threads/:id` uses `/api/channels/:id/messages` with the `chat.thread` template and `chat.threads.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Chat deploys as a Cloudflare-backed collaboration app with optional desktop and mobile client shells. ## Failure Modes - meeting join token flow drifts from guest or mobile launch flows - realtime or Durable Object bindings are unavailable - guest entry is mistakenly treated as normal workspace auth - a first-party widget origin or canonical resource header is absent from the shared Worker CORS policy, causing preflight to fail before Chat authorization runs ## Debugging Start with `/systems/topolo-chat`, then separate workspace-auth issues from guest and meeting-launch issues before debugging deeper. For a cross-app widget failure, inspect the `OPTIONS` response first: it should return `204`, reflect the allowed caller origin, and echo the requested authorization and canonical resource headers through the shared Worker runtime. ## Use It Open [Chat](https://chat.topolo.app) for the human product surface. The [system handbook](/systems/topolo-chat) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-chat --json topolo actions --service topolo-chat --json topolo actions capabilities --service topolo-chat --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-chat) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Chat and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Released exact source `bdd5b110982ff4e77e0416c72bd300d241f74af6` to staging and production on 2026-08-10 with one D1-held `tprk1` application root under the Store-only environment master. Protected fields use `tp2`, scoped blind indexes derive from `tpk1` data keys, and the administrative surface contains root diagnostics, root provision/rewrap, data-key rotation, and a read-only canary. Production reports zero unprotected fields or objects. - Verified staging source `c3c4e9c772516a2ccad3e4f84c3b330ad81b1af2` on 2026-08-01: the final wildcard override is removed, live preflight denied an untrusted origin without credential headers, and both tested first-party origins were reflected by the shared allowlist. - Reconciled Chat staging `9f2f0649e187` on 2026-07-31. Chat removed its app-local wildcard CORS implementation and now delegates preflight and response headers to the shared Worker runtime, which reflects allowed Topolo origins and canonical resource headers for the cross-app widget. - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloChat` `origin/staging` `0270c5f5661e` on 2026-07-27. - Reconciled this page against `apps/TopoloChat` `origin/staging` `d8e25b13511d` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloChat commits through d487fd0; reviewed 58 commits since 2026-06-25, including d487fd0 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 910917a chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); b577a36 Stop blocking startup on i18n readiness; 8ddd18d Remove meeting join scaffold overlay. - Persisted lightweight cross-app Chat widget UI state through Auth preferences on 2026-07-02 while keeping message content in Chat. - Added cross-app Chat widget ownership and widget API coverage on 2026-06-18. - Renamed Chat's local tenant-scoping API and D1 columns from workspace to organization on 2026-05-10. - Removed hard-coded Chat Auth app IDs on 2026-05-13 so login, callback preboot, worker auth validation, notification events, widget output, API-key management, and seed intake use slug-resolved app identity. - Verified Chat staging origin isolation on 2026-04-30. - Removed Chat's hosted Auth redirect from `/login` on 2026-04-20 so first-party users sign in through the branded embedded shared LoginPage. - Removed the Chat worker's residual local `TOPOLO_JWT_SECRET` handoff on 2026-04-18 so protected workspace bearer-token requests validate through Auth. - Delegated Chat web login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18. - Added service-scoped Auth cookie hydration to Chat startup on 2026-04-18 so returning users can enter without a full hosted login redirect. - Standardized Chat admin permission checks on 2026-04-10 so API key management now follows the shared Auth permission model instead of local role checks - Standardized the public product label to `Chat` across the web shell, workspace bootstrap text, and meeting handoff flows on 2026-04-04 - Added canonical Topolo Chat coverage and retired repo-local collaboration docs on 2026-03-30 ## TopoloCommerce Canonical URL: https://docs.topolo.app/applications/commerce Public overview of the multi-vertical commerce platform for venue operations, guest runtimes, and staff execution. ## What It Is TopoloCommerce is the multi-vertical commerce platform for teams that need one operating system across many venues. It supports: - one Topolo org with many venues - shared commerce foundations - venue-level module packs for hospitality, retail, or service workflows - guest-facing and staff-facing runtime surfaces in the same platform model ## Architecture TopoloCommerce is organized as a multi-surface workspace: - Worker API - signed-in operations app - signed-in tablet-first station app - public guest web runtime - managed mobile guest runtime - local Venue Edge runtime The platform resolves effective venue behavior from org defaults, venue overrides, and preset-based module packs instead of hardcoding one vertical operating model. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. Commerce's authenticated `GET /api/widget` uses that same platform-owned grant list and selects its explicit default when a widget request does not name a workspace; Commerce contributes only the workspace-scoped venue statistics. Programmatic `venues.create` calls require a stable `clientMutationId` so Auth workspace creation and Commerce venue provisioning can be retried and reconciled as one operation. ## Runtime Surfaces See `/systems/topolo-commerce` for the current runtime inventory. The main public-facing understanding is: - staff and chain operators use the signed-in ops app plus a separate tablet-first station app for kitchen, POS, bar, and expo execution - authenticated orgs without any venues now enter a first-venue onboarding flow instead of an empty dead end - the signed-in ops app now uses canonical venue-scoped URLs in the form `/venues/:venueId/...` - the signed-in ops app now presents venue context and queue state more like a live command center than a generic admin dashboard - the signed-in ops app now surfaces section coverage, staffing readiness, and member workload inside the live queue and team workspaces - the signed-in ops app now includes filterable live lanes with a ticket inspection rail plus ready-now and coverage-gap staffing views - the signed-in ops app now includes a venue Experience Studio so operators can set guest browse mode, palette, typography, logo, quick-action treatment, guest draft-timer policy, and shared tab opening requirement per venue - guests use venue-scoped web or managed-device surfaces that can now submit live orders, service requests, and bookings - guest writes now target only active venues, so unpublished venues cannot keep receiving sessions or orders through stale client state - the public guest host reserves platform-style paths such as `/dashboard`, `/login`, `/callback`, and `/auth/*` and redirects them to the guest landing instead of treating them as venue slugs - the public guest-web runtime now uses a stronger editorial landing, vertical-specific venue presentation, venue-configurable guest modes (`classic_menu`, `story_menu`, `reel_menu`), and a touch-first basket layout instead of a generic venue grid plus flat catalog view - direct venue pages now assume QR or table-link entry and therefore do not expose an in-app back path to the venue picker by default - `story_menu` and `reel_menu` now keep browsing and ordering inside immersive full-screen viewers instead of relying only on flat inline cards - guest ordering now behaves like a short-lived draft session, so nothing is sent until the guest reviews and places the full order, while the in-progress basket is mirrored through the venue queue Durable Object so back-of-house staff can see incoming intent before final submission, guests see a venue-configurable countdown before draft reset with an extend option near expiry, table QR flows now open with an explicit `Create new tab` or owner-approved `Join tab` choice instead of silently minting a new shared session, venues can optionally require a tab-owner photo reference before a new shared tab opens, refresh restores the current table tab on the same device, and the guest bill or tab flow now keeps prior payments visible when new orders are added instead of resetting the whole visit as unpaid - immersive story and reel views now expose direct basket access, current-item removal, a local `Maybe` path inside the short-lived draft session, and in-view add/customize actions, with `story_menu` supporting swipe navigation, swipe-down dismiss, compact review state in the header, an isolated equal-size split action row, visible action feedback, automatic progression with hold-to-pause behavior, a static Instagram-style story shell, and copy or ordering controls layered over the portrait media, plus compare-at price and bundle merchandising where configured, and `reel_menu` using TikTok-style vertical swipe/scroll snap navigation between section items plus a right-side vertical position rail - immersive story and reel views now also use reduced-motion-safe transition choreography rather than abrupt item swaps - voice capture now sits behind a floating circular launcher in the guest runtime, opens into a compact drawer with one oversized listen/stop control so guests can keep browsing while they speak, stays quiet until real speech or typed content exists, then responds through a chat-style voice feed with confirmations and direct basket review actions, prefers server-side transcription of the captured recording through Nexus when available, treats that captured audio as the authoritative transcript source instead of biasing it with the browser draft transcript, uses a low-cost Cloudflare first-pass parser, escalates to `gpt-5.4-mini` only for ambiguous or higher-risk requests, returns guest-facing response copy in the request language by default, supports on-demand translation backed by a reusable D1 translation cache, and can still escalate to staff review with transcript plus optional recording playback when browser capture is available - venue teams can manage sections, assign staff resources, and work live queue items as they arrive - venue teams can also open `station-commerce.topolo.app` for a live staff-station surface, where Point of Sale now follows `checkout_support` tickets, Bar Board projects beverage and pickup-adjacent work from the shared queue, Expo Window combines kitchen, dispatch, and handoff-ready pickup work on a tablet-first board, ticket movement appears across station tablets immediately through the Commerce live queue stream, and staff can open richer ticket details plus update ticket assignment directly from the station UI - Point of Sale discounts now use venue action permissions: routine discounts follow the configured threshold, higher-risk discounts require credential confirmation, full comps require the canonical manager-class action, and the displayed amount matches the server-persisted order and ticket totals - the station surfaces now adapt more intentionally across screen sizes, keeping the multi-lane board on larger displays while switching to a compact lane-selector plus bottom-sheet ticket detail flow on phone-sized screens - venue operators can now edit the live venue catalog from ops in a stronger merchandising workspace instead of only viewing seeded catalog content - venue operators can now review imports with visible source provenance, vertical context, timestamps, and operator notes before approving draft content - guest and ops surfaces now keep cached local state and replay queued actions after temporary cloud interruption - the local Venue Edge runtime can now run in `edge_preferred` or `cloud_preferred` mode so venues can keep edge as the normal hot path or keep cloud as the hot path when required - the local Venue Edge runtime now syncs all currently supported edge-authored operational records into Commerce cloud for visibility instead of only syncing a journal subset, including current team administration, venue device registration, shared-terminal identity methods, device-session attribution, and payment-reconciliation markers - station identity policy now exposes only implemented PIN and managed-device methods; cloud, Venue Edge, and native station runtimes share the same salted PBKDF2 PIN contract instead of accepting legacy or placeholder credential types - the local Venue Edge runtime now also syncs venue sync-policy changes plus staff notification and notification-acceptance state, and it reports current rescue-uplink activation posture back into Commerce cloud when connectivity is available - replay-safe guest writes now cover guest sessions as well as orders, service requests, and bookings - live queue reads now fall back cleanly to D1 if the Durable Object snapshot cache is unavailable - signed-in venue workspaces are scoped to the authenticated Topolo org and no longer fall back to demo venues when a different org signs in - public guest venue discovery now resolves from live active venues instead of a hidden default demo org - normal guest and ops runtimes now use only live Commerce data or cached real snapshots; demo content is reserved for explicit local demo mode and is consolidated under `topolo-demo-suite` - the shared `topolo-demo-suite` demo org now carries a richer multi-vertical Commerce dataset instead of a Commerce-only duplicate demo org - replayed guest and ops writes now carry stable `clientMutationId` values so temporary connectivity loss does not create duplicate venue records during recovery - venue operators can now inspect a dedicated resilience view showing the current cloud journal, recovery posture, and enrolled Venue Edge nodes for a venue - venue boards and DOOH outputs publish through the existing Nodo runtime ## API Reference The current route families cover org context, module resolution, venue list and creation, venue detail, venue experience reads and saves, catalog reads and saves, venue resilience state, venue sync-policy reads and writes, Venue Edge node enrollment and sync, guest venue discovery, guest-session creation, explicit table-tab creation or join approval for QR-scoped tables, live draft-order sync, live order and request submission, voice-intent resolution, voice response translation, queue reads and transitions, live queue streaming, team management, staff-identity-method reads and writes, device-state reads, staff-notification reads and acceptance writes, payment-reconciliation reads and writes, import approvals, and payment-session creation. Public guest writes accept only active venues, staff assignment writes reject invalid section or staff ids instead of clearing them implicitly, and queue ticket writes can reject stale optimistic-concurrency tokens when an operator acts on an out-of-date ticket copy. The venue experience contract now also includes per-venue `orderIntentTimer` settings that drive the guest-visible countdown and extend window plus `tableTabs.openingRequirement`, where `none` keeps name-only tab creation and `photo_reference` requires a one-time tab-owner reference image before the API opens a new shared tab, then removes the stored object on a best-effort basis when the owner closes that tab. The live draft-order contract mirrors in-progress guest baskets through the same venue queue Durable Object that powers back-of-house live state, those drafts remain visible until the guest explicitly clears or submits the basket, table-scoped guest flows now use owner-created shared tabs with explicit join approval plus per-member access checks on guest writes, refresh restores the active shared tab on the same device, and the finalized order route clears the matching draft preview once the guest commits. Voice-intent resolution now prefers Nexus Cloudflare transcription with `@cf/openai/whisper-large-v3-turbo`, then a low-cost Cloudflare parser with `@cf/meta/llama-3.1-8b-instruct-fast`, and only escalates to `openai/gpt-5.4-mini` when the cheap pass is ambiguous or higher-risk, with Commerce calling Nexus through an internal service binding in production, returning guest-facing response copy in the request language, reusing cached text translations through D1, and retaining xAI plus heuristic safety nets behind that. The current resilience contract also includes replay-safe guest and staff mutations for the browser outbox model plus the first full Venue Edge contract: bootstrap, journal pull, event push, cursor acknowledgement, and a local runtime that can operate with edge or cloud as the preferred hot path. Use `/systems/topolo-commerce` plus the internal handbook for the current route inventory. ## Auth and Permissions The signed-in ops and station surfaces use shared Topolo Auth and the first-party suite launcher contract. Browser callback-code redemption runs through the synchronized `@topolo-io/auth-client` package and rejects direct token callback parameters. Branded first-party `/login` routes render without an initial unauthenticated Auth refresh probe; protected app boot still uses cookie refresh. Improve Topolo stays in the authenticated account menu instead of standalone report buttons. Auth service metadata for the `topolo-commerce` service slug must allow both `https://commerce.topolo.app` and `https://station-commerce.topolo.app` as browser callback origins. Protected staff API bearer tokens are validated through Auth `/validate`; Commerce does not keep a local JWT-secret trust path. Commerce also follows the canonical Auth role ladder. Platform-wide bypass belongs only to `platform_super_admin` and `platform_admin` users in the Auth `admin` org; org-scoped `super_admin` stays an org role and staff worker access still depends on explicit Commerce permissions. Guest surfaces are venue-scoped runtimes and do not behave like ordinary signed-in Topolo suite apps. ## Data Ownership TopoloCommerce owns venue configuration, module settings, catalog and menu data, guest sessions, carts, orders, service requests, bookings, queue state, device-assignment intent, and venue-specific publish metadata. Topolo Pay, Topolo Nexus, Topolo MDM, and Nodo continue to own their own execution domains. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/venues`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `venues:read`, `venues:write`, `settings:write`, `queues:read`, `service-requests:read`. - `/venues` uses `/api/venues` with the `record.list` template and `commerce.venues.list` data source. - `/venues/:id` uses `/api/venues/:id` with the `record.detail` template and `commerce.venues.detail` data source. - `/orders` uses `/api/orders` with the `record.list` template and `commerce.orders.list` data source. - `/service-requests` uses `/api/service-requests` with the `record.list` template and `commerce.serviceRequests.list` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments TopoloCommerce currently deploys to: - `https://commerce-api.topolo.app` - `https://commerce.topolo.app` - `https://guest.topolo.app` - `https://station-commerce.topolo.app` - `https://commerce-api.stg.topolo.us` in the Topolo-owned staging mirror CloudControl remains the source of truth for the current Worker, Pages, and storage bindings. ## Failure Modes - venue behavior drifts from the shared module-resolution contract - guest and staff boundaries blur and the wrong runtime surface inherits the wrong auth or launcher behavior - venue team and assignment state drifts from the live queue model and breaks traceability - venues depend on cloud reachability because cached-local replay behavior is removed or bypassed - venues depend on replaying non-idempotent writes and create duplicates after short connectivity loss - venues lack visibility into their own recovery posture because resilience state is not surfaced in the signed-in workspace - venues cannot advance toward full local authority if edge enrollment and cursor sync drift from the canonical Commerce contract - venues can lose cross-venue visibility if edge-authored operational records stop syncing into cloud canonical state - platform integrations such as MDM, Pay, or Nodo are treated as local Commerce responsibilities instead of contract boundaries ## Debugging Start with `/systems/topolo-commerce` and the current internal handbook when checking route availability, venue behavior, or module-driven UI visibility. ## Use It Open [TopoloCommerce](https://commerce.topolo.app) for the human product surface. The [system handbook](/systems/topolo-commerce) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-commerce --json topolo actions --service topolo-commerce --json topolo actions capabilities --service topolo-commerce --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-commerce) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloCommerce and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloCommerce` `origin/staging` `e7811c634435` on 2026-07-27. - Reconciled this page against `apps/TopoloCommerce` `origin/staging` `e3d318efe657` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloCommerce commits through 2a9d72a; reviewed 393 commits since 2026-05-14, including 2a9d72a chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 108c013 Stop blocking startup on i18n readiness; 0cca0fa Adopt canonical Topolo typography; 6557147 Fix Commerce dashboard queue translations. - Updated public coverage on 2026-05-12 to document that Commerce keeps Improve Topolo inside the authenticated account menu. - Updated public coverage on 2026-04-20 to document that Commerce ops and station branded login routes use the synchronized auth client without an initial unauthenticated refresh probe. - Updated public coverage on 2026-04-19 to document the station Commerce Auth callback origin required for `station-commerce.topolo.app` sign-in. - Updated public coverage on 2026-04-18 to document synchronized shared-auth callback handling for the signed-in ops and station surfaces. - Updated public coverage on 2026-04-16 to document venue-configurable shared-tab opening requirements, including optional tab-owner photo reference capture before a new tab opens - Updated public coverage on 2026-04-16 to document the new table-tab entry model for QR-scoped tables, where guests must create a new tab or request to join an active one, tab owners approve joins, guest writes are checked against active membership, and fully paid tabs can be explicitly closed back to the chooser instead of silently starting over - Updated public coverage on 2026-04-15 to document live draft-order previews between guest baskets and back-of-house queue screens through the venue queue Durable Object - Updated public coverage on 2026-04-15 to document the live station-web staff surfaces for kitchen, POS, bar, and expo execution - Updated public coverage on 2026-04-15 to document that station-web now consumes the Commerce live queue stream for immediate cross-screen ticket updates - Updated public coverage on 2026-04-15 to document direct ticket assignment plus phone-friendly responsive station flows in station-web - Updated public coverage on 2026-04-11 to document that the checked-in ops and guest browser runtimes no longer expose `VITE_SKIP_AUTH` preview branches and now use only live or cached Commerce data paths - Added canonical TopoloCommerce public coverage on 2026-04-10 for the new multi-vertical org-to-venue commerce platform - Updated public coverage on 2026-04-10 to include the live queue stream and team-management contract now present in production Commerce - Updated public coverage on 2026-04-10 to include the current cached-local resilience foundation for guest and ops surfaces - Updated public coverage on 2026-04-10 to include replay-safe guest and ops writes for the current cached-local resilience foundation - Updated public coverage on 2026-04-10 to include the signed-in venue resilience view and cloud-side venue event journal - Updated public coverage on 2026-04-10 to include Venue Edge node enrollment and the cloud-side bootstrap plus journal-sync contract - Updated public coverage on 2026-04-10 to include live catalog editing from the signed-in ops surface - Updated public coverage on 2026-04-10 to include authenticated org-scoped staff workspaces and canonical `/venues/:venueId/...` ops URLs - Updated public coverage on 2026-04-10 to clarify that demo content is not a normal runtime fallback outside explicit local demo mode - Updated public coverage on 2026-04-10 to clarify that public guest venue discovery reads live active venues instead of a hidden demo-org fallback - Updated public coverage on 2026-04-10 to clarify that Commerce demo content is consolidated under `topolo-demo-suite` - Updated public coverage on 2026-04-10 to clarify that the shared `topolo-demo-suite` org now holds the richer Commerce demo dataset in place of Commerce-only duplicate demo ownership - Updated public coverage on 2026-04-10 to reflect the current guest-web production pass structure and the stronger vertical-specific guest runtime presentation - Updated public coverage on 2026-04-10 to reflect the richer staffing-aware queue and team workspaces now present in the signed-in ops app - Updated public coverage on 2026-04-11 to document guest-host reserved path redirects for platform-style routes such as `/dashboard` - Updated public coverage on 2026-04-11 to document venue-configurable guest browse modes plus the new ops Experience Studio for guest branding and presentation control - Updated public coverage on 2026-04-11 to document the local Venue Edge runtime, its `edge_preferred` and `cloud_preferred` modes, the requirement that current edge-authored operational records sync back into Commerce cloud, and the current team, identity-method, and device/session administration support in that edge contract - Updated public coverage on 2026-04-11 to document edge-side payment reconciliation markers for external terminal, cash, house-account, and deferred settlement flows - Updated public coverage on 2026-04-12 to document venue sync-policy control, staff notification acceptance, and rescue-uplink runtime reporting in the current Venue Edge contract - Updated public coverage on 2026-04-12 to document that direct venue entry no longer exposes an in-app back path and that `story_menu` or `reel_menu` now keep basket access and ordering inside immersive full-screen viewers, with `reel_menu` using vertical snap navigation ## TopoloCompose Canonical URL: https://docs.topolo.app/applications/compose AI-native document generation, revision, styling, and export for formal documents in Topolo. ## What It Is TopoloCompose is the Topolo workspace for creating, reviewing, revising, and exporting formal documents with AI. The Compose workspace is a document-first workbench with a separate two-column Plan surface and a wide Review draft canvas with focused document-side inspectors. It combines brief templates, inspectable generation briefs, editable document-type draft plans, draft-readiness preflight planning, selected source-pack evidence, imported text/Markdown/CSV/JSON evidence files, source material, generated drafts, review/edit modes, markdown autosave, citation intelligence, private suggestion previews with change review, selectable document sections, focused-section revision, citation-aware quality checks, targeted revision actions, Word/HTML/Markdown/RTF/text/print export controls, and share actions without forcing source setup and draft editing into the same body. Topolo People can open Compose with employee document context so common HR documents can be drafted from People in one action. ## Architecture The application uses the shared Topolo shell, Topolo Auth, and Nexus-backed AI model routing. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The production host is `https://compose.topolo.app`. ## API Reference Authenticated document generation, private suggestion, and revision routes live under `/api/documents/*`. People-to-Compose document requests use authenticated Compose sessions and prefilled document intents from Topolo People. ## Auth and Permissions Signed browser and API requests use Topolo Auth through the app id resolved from the stable `topolo-compose` service slug. ## Data Ownership TopoloCompose owns document workflows, document-domain state, mode-separated planning/review/export presentation, inspectable generation-brief assembly, editable document-type draft planning, draft-readiness preflight scoring, selected source-pack evidence, imported file evidence in the browser planning session, markdown draft editing, citation-coverage analysis, selectable section focus, private suggestion approval and change review, quality review presentation, source-review preparation, and client-side export actions. Nexus owns outbound AI provider invocation and model preference routing. ## Mobile Experience The checked-in mobile experience contract is **published** in `native_capability` mode. Its fallback route is `/documents`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/documents` uses `/api/documents` with the `record.list` template and `compose.documents.list` data source. - `/documents/:id` uses `/api/documents/:id` with the `record.detail` template and `compose.documents.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments The production host is `https://compose.topolo.app`. ## Failure Modes - generation fails when Nexus rejects or cannot route the caller's authenticated AI request - employee document generation does not start when a People intent is missing required prompt context - service slug resolution or deployment Auth-origin metadata can drift while the product is still planned - durable document persistence is not introduced until the org-scoped document model lands ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Compose](https://compose.topolo.app) for the human product surface. The [system handbook](/systems/topolo-compose) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-compose --json topolo actions --service topolo-compose --json topolo actions capabilities --service topolo-compose --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-compose) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Compose and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloCompose` `origin/staging` `3bd51606ef58` on 2026-07-27. - Reconciled this page against `apps/TopoloCompose` `origin/staging` `468820b46a11` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloCompose commits through af31198; reviewed 187 commits since 2026-06-13, including af31198 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); bdb88b5 Stop blocking startup on i18n readiness; 4927e67 Adopt canonical Topolo typography; 59d9a75 Lazy load Compose shell. - Upgraded the Compose workspace on 2026-06-13 into a document-first workbench with a separate two-column Plan surface, a wide Review draft canvas with focused revision inspector, and an Export inspector; brief templates, inspectable generation briefs, editable document-type draft plans that shape generation before the model call, draft-readiness preflight scoring with unresolved evidence-gap checklisting, source-pack controls and imported text/Markdown/CSV/JSON evidence files that attach selected evidence to generation and revision, citation intelligence for supported/unsupported claims, private suggestion previews with line-level change review and explicit accept/discard, selectable outline sections, focused-section revisions, review/edit modes, markdown autosave, citation quality gates, source-review actions, targeted revisions, multi-format client-side exports, share actions, and responsive desktop/mobile layout checks. - Centralized runtime app identity on 2026-05-13 so Compose resolves the `topolo-compose` slug instead of compiling concrete app ids. - Added TopoloPeople employee document launch support on 2026-04-27. - Added the initial TopoloCompose product surface on 2026-04-27. - Deployed Worker/static-assets baseline to `https://compose.topolo.app` on 2026-04-27. ## Topolo Consent Canonical URL: https://docs.topolo.app/applications/consent Consent, privacy permissioning, GPC enforcement, DSR, and audit infrastructure for Topolo products and customer surfaces. ## What It Is Topolo Consent is the Topolo Platform consent and privacy permissioning service. It is designed for websites, native apps, AI agents, kiosks, IoT surfaces, and Topolo-powered organizations that need a shared answer to whether data can be used for a specific privacy, analytics, marketing, or operational purpose. The SDKs and API surface includes copyable web, Flutter, iOS, and Android quick-start snippets for the selected workspace. Native SDK onboarding uses platform sub-tabs, shows the publishable SDK key, active methods, local-first/offline sync behavior, and app identifiers, and avoids implying one native SDK is dominant. Native app identifiers are configured from the selected workspace surface settings. They represent the allowed Flutter app ID, iOS bundle ID, and Android package name for that workspace, and the workspace switcher can mark one active workspace as the organization default. Authenticated Consent sections expose direct URLs for dashboard, configuration, preference builder, cookie scanner, SDKs/API, DSR requests, audit logs, and settings so operators can open or share a specific admin surface without re-navigating from the dashboard. ## Architecture Topolo Consent uses a Cloudflare Worker for public SDK/config APIs, admin APIs, SDK delivery, and ongoing cookie scanning. The read path is cacheable and local-first, while consent writes are explicit-project-key scoped, idempotent, and queue-friendly for high-volume traffic. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces Hosts: - production: `https://consent.topolo.app` - staging: `https://consent.stg.topolo.us` ## API Reference Core routes: - `canUseData(identity, purpose)` through `POST /api/can-use-data` - `getConsent` through `GET|POST /api/get-consent` - `setConsent` through `POST /api/set-consent` - `syncIdentity` through `POST /api/sync-identity` - `exportAudit` through `POST /api/export-audit` - `submitDSR` through `POST /api/submit-dsr` The public read path is cacheable and local-first. Public config resolves the effective regulatory mode from the end user's Cloudflare country and region, with the configured workspace mode used only as a fallback when location is unavailable. Unknown projects and unknown non-essential data use fail closed, while essential app functionality stays unblocked. Project configuration can include a visible operational compliance profile for jurisdictions, rights, opt-out signals, native-app controls, retention posture, and verification checks. Public SDK calls must include a project key. Production does not serve implicit demo configuration when a project key is missing or unknown. Person-likeness access is not authorized by Consent alone; Agent/Auth and Voice own that subject-user and company-admin authorization boundary. ## Auth and Permissions The admin dashboard uses Topolo Auth through app id `app_8FIGR7Q7zP9r`. Authenticated operators see the first-party short name `Consent` in the platform shell, can switch workspaces and create new workspaces from the top toolbar switcher, then use the single combined Dashboard that opens on consent-rate KPIs, restricted-use blocks, governed surfaces, and compact dashboard tabs for Overview, Consent, Rights, Signals, and Evidence. Granular charts for purpose activity, DSR pipeline, signal coverage, recent audit evidence, and compliance posture live behind those tabs rather than all competing on the first screen. Workspace creation and detailed setup live in the switcher and Configure surface rather than the primary Dashboard. Cookie Scanner monitors configured domains for server-set cookies and known vendor script hints, categorizes findings by purpose, and preserves compact scan history. Archived workspaces remain visible to authenticated operators but no longer serve public SDK configuration. Deletion is guarded when consent, DSR, or audit records exist. Public SDK routes are available before login because customer sites and native apps must capture consent before a user has a Topolo session. The admin UI follows the shared Topolo platform shell. Workspace selection and creation happen from the top toolbar, while Configure edits the active workspace through focused tabs for settings, surfaces, purposes, and vendors. Cookie Scanner monitors configured domains for server-set cookies and known vendor script hints, categorizes findings by purpose, and preserves compact scan history. DSR intake does not seed fake customer data, and Settings edits the active workspace legal profile and verification checklist. ## Data Ownership Consent state, consent events, project configuration, cookie scan history, DSR requests, and audit exports are organization-scoped at the service boundary. Web, Flutter, Swift, and Kotlin SDKs use publishable SDK keys, cache configuration locally, evaluate network-backed `canUseData`, queue consent writes, and keep host apps working when the network is degraded. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/projects`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/projects` uses `/api/projects` with the `record.list` template and `consent.projects.list` data source. - `/projects/:key` uses `/api/projects/:key/config` with the `record.detail` template and `consent.projects.detail` data source. - `/dsr` uses `/api/dsr-requests` with the `task.queue` template and `consent.dsr.list` data source. - `/dsr/:id` uses `/api/dsr-requests/:id` with the `record.detail` template and `consent.dsr.detail` data source. - `/audit` uses `/api/logs` with the `activity.timeline` template and `consent.audit.timeline` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Deployment metadata lives in `apps/TopoloConsent/topolo.cloudcontrol.json`. Production deploys from `main`; staging deploys from the `staging` branch. The service uses the standard Topolo local CI/deploy contract, `pnpm@10.11.0`, and published Topolo platform packages rather than local package links. Production and staging are provisioned with D1, KV, Queue, and R2 bindings. The public readiness route at `GET /api/readiness` reports whether those bindings are available without exposing secrets. The SoulCycle demo is an authenticated staging workspace linked to the staging Auth org `SoulCycle Pitch Demo`; it is accessed through the normal Topolo Consent sign-in flow. The demo is configured as a CPRA-first representative enterprise workspace with GPC, Do Not Sell or Share, Google Consent Mode v2, ATT, Android consent surfaces, DSR samples, and audit evidence. It is not legal advice or legal certification. Topolo also dogfoods Consent on the public TopoloOne marketing site through the `topolo-one-marketing` project. On staging, `stg.topolo.us` loads the Consent web SDK from `https://consent.stg.topolo.us` and records analytics, personalization, and advertising decisions from the host site's banner while keeping the host site local-first if Consent is degraded. ## Failure Modes - Unknown non-essential purposes fail closed. - Missing project keys fail closed or return `project_key_required`. - GPC opt-out signals deny restricted purposes before remote lookup. - SDK network failures queue writes and do not block host rendering. - Cookie scan target failures are recorded per domain and do not stop consent collection. - Admin dashboard downtime does not stop public consent collection, and the dashboard shows a degraded state instead of fabricated project data. - GDPR or marketing consent is treated as authorization to impersonate a person's likeness. ## Debugging - `GET /api/config?projectKey=soulcycle-demo` - `GET /api/config?projectKey=soulcycle-demo` with Cloudflare country/region headers in tests - `GET /api/config` - `GET /api/readiness` - `POST /api/can-use-data` - `GET /api/health` ## Use It Open [Topolo Consent](https://consent.topolo.app) for the human product surface. The [system handbook](/systems/topolo-consent) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-consent --json topolo actions --service topolo-consent --json topolo actions capabilities --service topolo-consent --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-consent) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Consent and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 5 published route(s) against `apps/TopoloConsent` `origin/staging` `038c0d005a69` on 2026-07-27. - Reconciled this page against `apps/TopoloConsent` `origin/staging` `95696e7307a9` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloConsent commits through 528e823; reviewed 100 commits since 2026-06-18, including 528e823 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); c48af2b Stop blocking startup on i18n readiness; edfe64e Compact scanner empty states; d1ea6e2 Fix consent project row action layout. - 2026-05-08: Added native SDK active behavior, end-user-location regulatory mode resolution, and cookie scanner coverage. - 2026-05-07: Clarified public Consent coverage as privacy/GDPR permissioning rather than the person-likeness authorization boundary. - 2026-05-07: Production admin UX verified for workspace switching, Configure tabs, focused add dialogs, SDK install snippets, audit exports, and DSR evidence workflows. - 2026-05-07: DSR intake now starts with empty customer fields and Settings can save legal profile/checklist changes. - 2026-05-06: Reworked the Dashboard into a tabbed customer-facing operations view that opens on KPIs and an executive overview, with granular Consent, Rights, Signals, and Evidence dashboards available without crowding the first screen. - 2026-05-06: Added TopoloOne public-site dogfooding through the `topolo-one-marketing` Consent project so staging can show Consent in use on a real Topolo-owned website. - 2026-05-06: Combined Overview and Dashboard into one Dashboard navigation entry, set platform chrome to the short name `Consent`, and added favicon, app manifest, Apple touch icon, and PNG Open Graph assets. - 2026-05-06: Completed runtime/deployment hardening with pnpm, published Topolo package dependencies, shared Worker error reporting, standard CI/deploy/ops workflows, and CloudControl quality targets. - 2026-05-06: Corrected staging deployment metadata so staging deploys from the `staging` branch, while production remains on `main`. - 2026-05-06: Updated Consent to the shared UI Kit release that persists dark/light mode as a user-level Topolo platform preference. - 2026-05-06: Reframed the former Projects page as a workspace Dashboard combining active workspace context, readiness, lifecycle controls, registry actions, and create-workspace access. - 2026-05-06: Added visible project compliance-profile support and configured the authenticated SoulCycle staging workspace with CPRA-first operational settings, representative vendors, DSR samples, native consent posture, and audit evidence. - 2026-05-06: Moved active project switching into the top toolbar as a workspace-style project switcher with create-project access inside the menu. - 2026-05-06: Added authenticated Projects management for archive, restore, and guarded deletion. - 2026-05-06: Added an always-visible `New project` action in the authenticated dashboard header so operators can create additional organization-scoped projects without hunting through Configure. - 2026-05-06: Retired the legacy demo browser path entirely; the SoulCycle demo is only the authenticated Consent platform workspace. - 2026-05-06: Added authenticated configuration, consent-builder, DSR status/intake, audit filter, and audit export workflows. Public APIs now require explicit project keys instead of falling back to demo configuration. - 2026-05-06: Admin dashboard data is now organization-scoped and backed by persisted project, audit log, and DSR rows; unknown project keys fail closed on public APIs. - 2026-05-06: Production Cloudflare data resources were provisioned and bound for the Consent Worker. - 2026-05-06: Staging Auth now has a `SoulCycle Pitch Demo` org for the authenticated Consent demo. - 2026-05-06: Staging was provisioned with Cloudflare data resources and an authenticated SoulCycle workspace seed. - 2026-05-06: Topolo Consent created as a first-party Topolo application/service from the Consent OS execution plan. ## TopoloCRM Canonical URL: https://docs.topolo.app/applications/crm Public overview of the CRM service, pipeline surface, SDR inbox control plane, and developer-key access model. ## What It Is TopoloCRM is the customer and pipeline management surface for contacts, companies, deals, tasks, real-estate-oriented records, and the SDR email inbox/control plane. ## Architecture CRM combines the application UI with a worker/backend surface that owns CRM data access, attachments, API key developer access, and the first-party auth/session integration path. For SDR operations, CRM now owns live campaign, sequence, lead, and thread state while reusing the existing ticket conversation model for immutable email history. The authenticated CRM interface uses the shared Topolo shell for suite-wide search, theme switching, app switching, command-palette access, and bug reporting. Individual CRM module headers stay focused on CRM-specific actions such as imports, grid/list modes, saved views, record creation, filters, dashboard customization, and real-estate workflow controls. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces See `/systems/topolo-crm` for the current runtime hosts and worker deployment surfaces. ## API Reference Use `/reference/apps/topolo-crm` and the generated OpenAPI surface for the current route and operation map. The canonical docs application now replaces the older repo-local integration, SSO, cookie-migration, and API handoff docs. The SDR worker contract is exposed through `/api/sdr/*`, including control-plane CRUD, inbox reads, sendable-lead selection, pre-send guards, outbound/inbound/status ingest, and historical backfill endpoints. The contact import flow supports broader CSV auto-mapping for common enrichment exports, including names, emails, direct and mobile phone numbers, company, title/seniority, department, education level, external IDs, external profile URLs, location fields, LinkedIn profile URLs, and company metadata such as website/domain, HQ phone/fax, founded year, employee counts/ranges, and industry. Contact import can also create missing companies from the same spreadsheet, enrich matched companies with mapped company fields, and optionally preserve the original CSV row as import provenance. When the CRM worker is configured with its Cloudflare `AI` binding, preview uses AI-assisted field suggestions before the user confirms mappings. ## Auth and Permissions CRM developer-key management is controlled through Auth-validated org and service permissions. Its browser session path now uses the shared Topolo cookie-refresh auth client instead of a CRM-specific refresh implementation. CRM resolves its concrete Auth app id from the Auth catalog slug `topolo-crm` at runtime. The browser, backend, widget, API-key, and notification paths share the same source-owned app identity rather than hardcoding concrete app ids. Browser login and SSO callbacks delegate to the shared Auth client, including Auth `/sso/exchange` handling, so callback URLs carry one-time `sso_code` values rather than bearer tokens. Fresh callback codes are exchanged by the HTML preboot gate before React starts, with the React callback route kept as the fallback. CRM does not expose a legacy `/sso?token=` browser handoff route. The explicit `/login` route renders CRM's branded shared LoginPage directly, and shared Auth token/session update events are treated as already-persisted state so the app does not recursively re-emit the same token. The browser keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal reload should return to the CRM workspace rather than appearing signed out while cookie refresh catches up. Checked-in backend local defaults do not expose a skip-auth mode, keeping CRM's development setup aligned with the Auth-required production posture. ## Data Ownership CRM owns its domain records, attachments, pipeline data, and the live SDR email control plane while relying on Auth for identity and scope validation. OpenClaw remains the execution worker for SDR automation, but it now reads live state from CRM and writes all outbound, inbound, delivery, and suppression events back through CRM APIs. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/contacts`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `crm.contacts.read`, `crm.contacts.write`, `crm.companies.read`, `crm.companies.write`, `crm.activities.read`. - `/contacts` uses `/api/contacts` with the `record.list` template and `crm.contacts.list` data source. - `/contacts/:id` uses `/api/contacts/:id` with the `record.detail` template and `crm.contacts.detail` data source. - `/companies` uses `/api/companies` with the `record.list` template and `crm.companies.list` data source. - `/companies/:id` uses `/api/companies/:id` with the `record.detail` template and `crm.companies.detail` data source. - `/contacts/:id/activity` uses `/api/pipeline/:id/history` with the `activity.timeline` template and `crm.activities.timeline` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments CRM ships with a backend worker and a worker-backed frontend asset surface documented in the generated handbook. The Topolo-owned staging mirror runs the frontend worker at `crm.stg.topolo.us` and the API worker at `crm-api.stg.topolo.us`. ## Failure Modes - stale auth claims or missing admin permission on API key surfaces - storage/binding misconfiguration - route drift between UI and worker APIs ## Debugging Use `/systems/topolo-crm` for runtime and deployment detail, and `/reference/apps/topolo-crm` for the contract surface. ## Use It Open [TopoloCRM](https://crm.topolo.app) for the human product surface. The [system handbook](/systems/topolo-crm) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-crm --json topolo actions --service topolo-crm --json topolo actions capabilities --service topolo-crm --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-crm) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloCRM and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 5 published route(s) against `apps/TopoloCRM` `origin/staging` `77b3b882170a` on 2026-07-27. - Reconciled this page against `apps/TopoloCRM` `origin/staging` `4a2ce1fa703b` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloCRM commits through 8d834b0; reviewed 510 commits since 2026-05-14, including 8d834b0 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 452ef90 Add CRM API asset cache headers; 0cfe2dc Split CRM startup shell bundle; 320ebc6 Adopt canonical Topolo typography. - Centralized CRM app identity and moved runtime app-id use to Auth slug resolution on 2026-05-13; the CRM source and deployable JavaScript no longer carry concrete CRM `app_*` or `app_*` ids. - Verified the isolated Topolo Staging deployment on 2026-04-30; `crm.stg.topolo.us` and `crm-api.stg.topolo.us/health` returned HTTP 200. - Enabled same-tab browser session restore by default on 2026-04-23 so CRM reloads remain signed in after successful Auth handoff or refresh. - Hardened CRM's browser Auth provider and callback preboot gate on 2026-04-20 so `/login` renders without an initial refresh probe, shared Auth token events do not recursively re-dispatch the same token, and fresh callback codes are exchanged before React starts. - Removed duplicate CRM module-header shell utilities on 2026-04-19 so the shared shell owns suite controls while CRM pages keep domain actions - Fixed CRM contact creation placeholder drift on 2026-04-18 so authenticated contact writes align with the current expanded contact schema - Delegated CRM browser login URL construction and callback exchange to the shared Auth client on 2026-04-18 and removed the legacy `/sso?token=` browser route - Removed stale CRM backend local and test `SKIP_AUTH` defaults on 2026-04-18 so local worker setup no longer documents or carries a skip-auth mode - Promoted CRM browser SSO callbacks to Auth `/sso/exchange` on 2026-04-17 so callback URLs require a one-time `sso_code` instead of bearer tokens - Made CSV import field pickers searchable on 2026-04-06 so users can filter the available CRM target fields while mapping spreadsheet columns - Adjusted the CSV import preview layout on 2026-04-06 so wide spreadsheets no longer clip the mapping column and long sample values wrap inside the preview instead of being cut off - Expanded CSV import auto-matching and AI-assisted field suggestions for common lead-enrichment exports on 2026-04-06, including selective new first-party contact/company fields, direct company creation from contact imports, and optional raw-row provenance capture - Added CRM-owned SDR inbox/control-plane documentation for email operations and OpenClaw worker integration on 2026-04-01 - Moved companies onto soft delete semantics and aligned company dashboard/list reads to active rows on 2026-03-31 - Aligned the core dashboard contacts and deals totals with list semantics by excluding soft-deleted records on 2026-03-31 - Standardized TopoloCRM browser auth on the shared Topolo auth client on 2026-03-31 - Expanded canonical CRM coverage and retired repo-local CRM docs on 2026-03-30 ## Topolo Design Canonical URL: https://docs.topolo.app/applications/design Standalone brand-governed design workspace for static assets and short animated creative clips. ## What It Is Topolo Design is a standalone design workspace for creating brand-governed static assets and very short animated clips such as animated ad banners. It remains useful without Social Studio or Socialize. ## Architecture Topolo Brand owns mutable brand kits and immutable published versions. Design reads a published version and records that exact version in each composition. Design owns projects, editable compositions, lightweight per-layer motion, rendering, export metadata, and generated media bytes. Social Studio remains the richer multimedia production surface. Socialize owns social media libraries, posts, channels, schedules, and publishing. Design can hand a ready asset descriptor to either application without making either one a prerequisite and without publishing a post itself. ## Static And Animated Exports Design exports SVG, PNG, JPEG, and MP4. Short MP4 clips may run from 0.5 to 15 seconds at 12, 24, or 30 frames per second. Layer motion includes fade, slide-up, slide-left, zoom-in, and pulse presets with configurable timing and easing. The export panel calculates a deterministic estimated file size before rendering. Ready exports retain both that estimate and the actual uploaded byte size so people and agent workflows can compare expected and completed output. SVG is rendered by the service. PNG, JPEG, and MP4 use a create, bounded binary upload, and ready lifecycle. Browser MP4 export fails explicitly when the browser cannot record a native MP4 stream. ## Runtime Surfaces - `design.topolo.app` is the production application. - `design.stg.topolo.us` is the staging verification surface. - `design.topolo.dev` is the development surface. - Protected API routes cover projects, export estimation, export creation and retrieval, media upload, social handoff, widgets, bootstrap, and privacy lifecycle. ## Auth and Permissions Topolo Auth owns organization, application access, workspace identity, and the selected authorized workspace. Design persists only an identity mirror required for referential integrity and scopes every project and export to the verified organization and workspace. ## Data Ownership One environment-specific D1 database stores project and export metadata. One private R2 bucket stores generated PNG, JPEG, and MP4 bytes. Object content is reachable only through authenticated Design routes. Brand is consumed through a read-only service binding. ## API Reference Design publishes 16 credential-scoped actions. Read-only discovery covers widget and workspace bootstrap, available Brand versions, project list/get, export-size estimation, export retrieval, and privacy export. Confirmed mutations cover project create/update/archive/restore, export creation and upload, provenance-preserving handoff, and workspace erasure. Discover the current contract instead of guessing routes: ```bash topolo services --query topolo-design --json topolo actions --service topolo-design --json topolo actions capabilities --service topolo-design --json topolo actions get app_topolo_design.exports.estimate --json ``` The [Agent Actions reference](/reference/actions?service=topolo-design) exposes the same schemas, effects, confirmation rules, examples, verification, and recovery guidance. ## Deployments The same source tip promotes through isolated development, staging, and production Workers. Each environment has its own D1 database, R2 bucket, API Worker, web Worker, Brand service binding, Auth registration, and Developers action projection. ## Privacy Lifecycle `privacy.export` returns the selected workspace's Design projects and export metadata. Confirmed `privacy.erase` removes those records and their generated R2 objects for the same organization and workspace. The operation does not alter the referenced immutable Brand version or data owned by Social Studio or Socialize. ## Failure Modes - no authorized Design workspace is selected - a referenced published Brand version cannot be resolved - a composition contains invalid motion timing or an unknown layer reference - an MP4 duration or frame rate is outside the supported bounds - the browser does not support native MP4 recording - uploaded media has the wrong type or exceeds the 25 MiB bound - a handoff is attempted before the export reaches ready state ## Debugging Start with `/api/health`, then verify the Auth identity, organization, selected workspace, and current action permission. For animation failures, inspect clip duration, fps, layer references, and motion timing. For missing media, compare the export row, status, MIME type, and tenant scope with its private R2 object. ## Use It Open [Topolo Design](https://design.topolo.app) for the product surface. The [system handbook](/systems/topolo-design) records runtime topology, storage, permissions, action ownership, and verification evidence. ## Change Log / Verification - 2026-08-10: verified standalone animated creative, deterministic export-size estimation, the complete 16-action catalog, schema-valid published examples, and canonical notification-producer behavior against released TopoloDesign source `79e61a639b89a81c9233e21ef6126963b1381957`. Development, staging, and production passed the canonical build, typecheck, 102-test, 100%-coverage, changed-line coverage, and workspace conformance gates; both Workers, health checks, headless observation, and migration `0004_animated_exports.sql` were healthy at the exact released tip. ## Topolo Developers Canonical URL: https://docs.topolo.app/applications/developers Public overview of the authenticated Topolo developer portal and its submission/request workflows. ## What It Is Topolo Developers is the authenticated developer console for teams shipping into the Topolo ecosystem, and it also hosts the staff-only internal review and commerce operations areas for app submissions, Android and iOS mobile app artifacts, build requests, developer workspaces, app pricing, marketplace status, and payout readiness. ## Architecture The application is a standalone Cloudflare Worker at `developers.topolo.app` with Worker static assets, same-origin API handlers, bounded D1 directory/workflow indexes, and SQLite Durable Object partitions keyed by application. It owns mobile artifact catalog metadata for Android and iOS, complete published app manifests, and per-app machine-action definitions for SDK, CLI, and MCP agents. Topolo Auth supplies login, session refresh, API-key records and catalogs, app-switcher entitlement state, approved-app registration, and bounded per-app permission projections used by Developers during action discovery. The Credentials route uses the shared multi-application API-key screen rather than a Developers-owned credential manager. Public developer-program discovery still begins on TopoloOne, but the primary public handoff now lands on `developers.topolo.app/signup`. Signup creates the developer workspace account first, then onboarding continues inside the signed console instead of through a public marketing form. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The primary runtime host is `https://developers.topolo.app`, with `https://developers.topolo.app/signup` serving as the public signup entrypoint from the marketing site. Signed publisher routes include `/onboarding`, `/overview`, `/apps`, `/credentials`, `/requests`, and `/settings`. Internal staff review routes live at `/review/app-submissions` and `/review/build-requests`; internal Topolo commerce operations routes live under `/admin/*`. ## API Reference Topolo Developers owns the signed `/api/developer-console/*` backend contract for workspace summary, onboarding, app records, app action definitions and publication, mobile artifacts, submissions, build requests, transfer claims, internal review workflows, and internal commerce controls. It also owns cursor-paged public `/api/apps` catalog responses for installable Android artifacts by default, with iOS metadata available through the platform query. Responses contain `artifacts` and a `page` continuation object; limits are capped at 100. It consumes centralized Auth API-key, app-switcher entitlement, service-registration, and per-app permission routes documented in `/reference/api/topolo-auth`. Published action definitions can also carry a clean-room agent contract: public docs, canonical resource identifiers, effects, actionable errors and recovery, verification steps, rollback and next actions, and examples. Developers validates declared agent contracts and their root input/output schemas before publication, preserves them in the application partition, includes them in credential-scoped catalog responses, invalidates catalog digests when that metadata changes, and rejects a sync when the committed partition digest does not match the exact action set that was sent. Atomic manifest imports return the durable partition action count and `sha256-v1` digest after commit. The canonical publisher independently computes the expected digest and stops publication when that committed count, algorithm, or digest is missing or stale. Public application discovery is cursor-based: `/api/store/catalog` returns at most 100 applications plus `page.hasMore` and `page.nextCursor`, `/api/store/search` returns at most 40 ranked matches, and exact app reads hydrate one application partition. This keeps request cost bounded as the number of applications grows. Public `/api/apps` catalog responses include approved app artifacts whose Developers marketplace status is `active` or `production_ready`; developer-only, draft, paused, and archived apps stay out of the public artifact catalog. This lets production-ready Topolo-owned mobile APKs support device installs without promoting those mobile records into the public TopoloOne app-store catalog. The signed app-detail App Store marketing editor uses the same Developers-owned store taxonomy that TopoloOne and `topolo.io/app-store` consume, so publishers edit the same broad store section and detailed store category fields that appear on public catalog cards. Its public badge selector controls the visible App Store badge/tone, not runtime app access, and the public stage wording is derived from that badge instead of edited separately. Signed app forms label public store distribution as `Topolo App Store`. The underlying API value remains `distributionModel = "marketplace"` for compatibility, but the user-facing flow is not limited to third-party apps. Publication policy follows ownership. Approved operators use restricted `topolo-platform apps scaffold --provision` and `topolo-platform apps reconcile --apply` for Topolo-owned manifests. Customer developers use the public, confirmable `apps.scaffold` and `apps.reconcile` action contracts exposed through CLI/MCP discovery. Third-party changes remain subject to organization approval and default to organization-internal distribution; requesting Topolo App Store distribution cannot self-approve the listing. Operator-only Developers `admin.*` contracts are excluded from public agent discovery. ## Auth and Permissions Topolo Developers uses the shared Topolo browser auth client and Auth-managed route family. It should not introduce a separate account system. The app uses provisioned app-id bindings at runtime: `APP_ID=app_NjDq9G9qyyjr` for its own browser/backend Auth context, `AUTH_APP_ID=app_mKShvFV4c8Z3` for the legacy consent-forwarding loading surface, `P2P_APP_ID=app_4BzeLqH0wCve` for internal P2P sync calls, and `TOPOLO_SEED_APP_ID=app_topolo_seed` for staging seed routes. Plain sign-in is workspace-first: the signed console expects a Developers-owned developer profile for the current Auth organization rather than creating arbitrary workspaces on first access. Internal commerce operators can set approved app visibility to `active`, `developer_only`, `draft`, `paused`, or `archived`. Platform-wide commerce access is reserved for Auth users whose role is `super_admin` in the `admin` organization, while delegated staff access still comes from explicit Developers `commerce:*` permissions. `developer_only` keeps the app usable only by the developer owner organization, with Topolo Auth enforcing that status across launcher, SSO, validation, API-key, and service-context checks. ## Data Ownership Topolo Developers owns authenticated console UX, workspace-scoped developer profiles and records, app drafts, complete published app manifests, app action definitions and the credential-scoped action catalog consumed by SDK, CLI, and MCP, mobile artifact metadata, submissions, build requests, transfer state, internal review-state data, app marketplace/pricing controls, payout-account readiness, and payout ledger events. Topolo Auth owns identity, sessions, app-scoped workspace identity and lifecycle, centralized API-key catalogs, app-switcher installation entitlements, approved-app registration into the shared service catalog, and bounded per-app entitlement and permission projections. The Topolo Technology workspace also carries first-party Topolo mobile artifact records. Topolo Feed, Topolo Provision, and Topolo MDM Mobile have system-specific records. Developers may retain Android/iOS identifiers and artifact history for the 22 archived `TopoloMobile*` Flutter repositories, but those catalog rows are not proof of an active source or release pipeline. Current mobile behavior comes from each active application's `topolo.mobile-experience.json`, TopoloProvision, or TopoloMDM; only artifacts built from an active owning repository may be promoted. ## Mobile Experience The checked-in mobile experience contract is **approved** in `web` mode. Its fallback route is `/overview`, its offline policy is `undefined`, and it requires organization context. Published permissions: none. - No native routes are published yet. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Developers deploys as the `topolo-developers-production` Worker on `developers.topolo.app` and the `topolo-developers-staging` Worker on `developers.stg.topolo.us`. The catalog cron worker points embeddings sync at the matching environment's `/api/catalog/embeddings` endpoint. The Worker assets binding serves the first-party browser icon assets from `/favicon.svg` and `/favicon.ico` so the deployed app tab uses the canonical Developers icon. The same Worker serves the mobile app catalog routes that device installers and sales-demo surfaces consume. Android APK artifacts for first-party mobile catalog rows are stored in the shared `topolo-apks` R2 bucket and served from the canonical `https://apk.topolo.app` host through immutable checksum-suffixed URLs plus latest aliases. Developers is also the canonical presentation owner for first-party catalog names and icons. Its guarded publication path requires approved first-party control records to have an icon, verifies that the published registry projection carries the same icon, and exposes that projection to Auth and shared clients without a generic identity fallback. Applications classified as `organization_internal` remain valid control-plane records but are deliberately excluded from the public registry projection. ## Failure Modes - `developers.topolo.app` serves the wrong Worker deployment or stale assets - callback and deep-link routes fail because the SPA fallback is missing - the portal drifts back into TopoloOne ownership instead of remaining a separate application - the local Developers API contract or the shared Auth identity/service-registration contract drifts from the portal UI assumptions - mobile artifact metadata is edited outside Developers and the public `/api/apps` catalog no longer matches approved application records - internal app commerce controls drift from Auth service-catalog marketplace metadata after approval - app visibility drifts so a developer-only app remains visible through public catalog, launcher, API-key, or service-context access - app action definitions drift from the service manifest permission catalog and fail Auth publish validation ## Debugging Start with `/systems/topolo-developers`, then verify the served Worker deployment and Auth session state before changing portal UI code. ## Use It Open [Topolo Developers](https://developers.topolo.app) for the human product surface. The [system handbook](/systems/topolo-developers) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-developers --json topolo actions --service topolo-developers --json topolo actions capabilities --service topolo-developers --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-developers) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Developers and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Clarified first-party automatic projection and third-party marketplace approval boundaries on 2026-08-10. - Reconciled action-catalog enrichment, runtime authorization, and versioned import normalization through `apps/TopoloDevelopers` `origin/staging` `4ee465b77d8c` on 2026-07-29. Runtime-authorized actions remain discoverable, while their owning application makes the final organization, resource, and input decision at call time. - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the web mobile experience contract and its 0 published route(s) against `apps/TopoloDevelopers` `origin/staging` `98d9b563c53e` on 2026-07-27. - Reconciled this page against `apps/TopoloDevelopers` `origin/staging` `753ff39fe7f5` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Added validated clean-room action metadata on 2026-07-14 so third-party CLI and MCP agents can discover schemas, examples, effects, recovery, verification, rollback, and next actions without repository access. - Replaced the Developers credential manager on 2026-07-12 with the shared multi-application API-key screen while preserving workspace access gating and Auth-backed application discovery. - Replaced global full-manifest catalog reads on 2026-07-11 with a compact paginated directory, bounded search, and per-application manifest hydration. - Added per-application SQLite partitions for complete published app manifests on 2026-07-10 so application count does not grow a global full-manifest storage object. - Reconciled workspace verification on 2026-06-28 against apps/TopoloDevelopers commits through fef0d94; reviewed 261 commits since 2026-06-04, including fef0d94 feat(catalog): bulk seed sync (publish all 47, then 2 bulk S2S calls); b18b735 feat(catalog): seed registry from Auth's full service catalog (47, not 11); a733358 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 8bfcd02 feat(catalog): seed backfills Auth org-service app_id mapping via S2S. - Added Developers-owned app action definitions on 2026-06-04 so publishers can manage machine-callable SDK, CLI, and MCP operations while Auth remains the permission-scoped projection boundary. - Replaced runtime Developers Auth slug lookups on 2026-05-13 with deployment app-id bindings so browser auth, shared shell, widgets, store proxy calls, Auth registration calls, P2P sync calls, and seed routes do not call Auth to discover stable app ids. - Verified Developers staging portal build and catalog-cron staging metadata on 2026-04-30. - Corrected the app-detail App Store marketing editor on 2026-04-27 so public catalog category and subcategory controls stay aligned with the Developers-owned store read model and the badge selector is no longer labeled as runtime status. - Simplified the app-detail App Store marketing editor on 2026-04-27 so existing TopoloOne store categories hydrate from `developer_apps.marketplace_subcategory`, the broad taxonomy bucket is labeled as a store section, and duplicate manual stage-label editing is removed. - Renamed the signed app-form distribution label on 2026-04-27 to Topolo App Store while preserving the existing API value. - Restricted the Developers platform-admin bypass to Auth `super_admin` users in the `admin` organization on 2026-04-23 while preserving explicit `commerce:*` staff permissions. - Switched the canonical first-party APK host from `topoloapk.topolo.app` to `apk.topolo.app` and promoted the TopoloProvision Android APK catalog row to core `1.2.172` on 2026-04-23. - Added developer-only app visibility controls backed by Auth service-status enforcement on 2026-04-23. - Published all 22 retained Topolo Mobile Flutter Android APKs from Developers to the shared `topolo-apks` R2 bucket and promoted their catalog rows to installable artifacts on 2026-04-23. - Finalized all 22 retained Topolo Mobile Flutter app package identifiers and removed 8 superseded mobile app records from the Developers catalog backfill on 2026-04-23. - Marked ClockMe, Inspirational, and Hiero as the first package-identifier-finalized retained Flutter batch on 2026-04-23. - Added Topolo Technology's retained Flutter mobile apps to Developers on 2026-04-23 as Topolo Mobile app records with Android and iOS metadata. - Added Topolo Technology's first-party mobile app records to Developers on 2026-04-23. - Moved mobile app artifact catalog ownership into Developers on 2026-04-22 so Android and iOS release metadata is managed from the app detail workflow and exposed from Developers-owned `/api/apps` routes. - Corrected the public Developers sign-in CTA on 2026-04-21 so first-party users open the app-origin shared login screen instead of hosted Auth. - Corrected the signed Credentials service selector on 2026-04-21 so Auth-backed API-key metadata requests use canonical app ids instead of organization-service access-row ids. - Backfilled the Topolo Technology publisher workspace and first-party Topolo Platform app records in production Developers D1 on 2026-04-21 so Topolo can use the developer console like an external publisher. - Seeded the shared Topolo demo suite developer workspace in production on 2026-04-20 so platform-wide auth audits can verify the signed console with `demo@topolo.io`. - Cut the signed Developers data path over to its own Worker + D1 backend on 2026-04-15 and removed request-time schema bootstrap in favor of checked-in D1 migrations plus a repo-level CI gate - Added internal Topolo commerce operations routes on 2026-04-16 so super admins can manage developer workspace state, app pricing/marketplace state, payout readiness, and payout ledger events inside Topolo Developers - Re-homed internal app-submission and build-request review into Topolo Developers on 2026-04-13 so staff operators now review queues from the same application boundary as publisher intake - Rebuilt Topolo Developers as the account-first developer console on 2026-04-13 so signed users now continue through onboarding, private app setup, public listing submission, and Auth-backed credentials inside the standalone app - Added the public signup handoff at `developers.topolo.app/signup` on 2026-04-10 so the marketing site can route developers into one clear entrypoint - Split the authenticated developer portal into the standalone Topolo Developers application on 2026-04-10 ## Topolo Device Platform Canonical URL: https://docs.topolo.app/applications/device-platform Public overview of Topolo's device distribution, feed delivery, analytics, Android playback, and provisioning surfaces. ## What It Is Topolo Device Platform is a family of Topolo-owned surfaces for feed delivery, feed media assets, feed analytics, Android playback, TopoloMDM-owned Android provisioning, and device-side consumption of Developers-owned app catalog metadata. ## Architecture The product family spans several first-class `PlatformApplications` roots rather than one unified application. TopoloFeed owns feed delivery, feed media assets, feed operator UI, Android playback, and feed analytics under `apps/TopoloFeed`. TopoloMDM owns device management and Android provisioning. Topolo Developers owns the Android and iOS app-catalog metadata that device install flows consume. The retained Nodo-origin mobile surfaces now appear as Topolo-owned mobile apps in the Developers workspace: Topolo Feed, Topolo Provision, and Topolo MDM Mobile. ## Runtime Surfaces Use `/systems/topolo-device-platform` for the current inventory of host acquisition, workers, UIs, and Android surfaces. ## API Reference The active contracts are curated in the docs platform and include TopoloFeed's `https://feed-api.topolo.app` feed worker, `https://topolo-feed-assets.topolo.app` media asset host, `https://feed-analytics-api.topolo.app` telemetry worker, Developers-owned `/api/apps` mobile artifact listings, and the Android consumers that depend on them. ## Auth and Permissions Auth expectations vary by surface. Some workers are lightweight delivery or analytics endpoints, while admin and provisioning flows should align with broader platform standards. Devices sign in with their own credential rather than a person's account, and that credential can be rotated for a single device without disturbing the rest of the fleet. ## Data Ownership Device-platform surfaces own feed configuration, feed analytics, playback state, and provisioning-related artifacts depending on the subcomponent. Feed-specific delivery belongs inside TopoloFeed; mobile app listing and distribution metadata belongs inside Topolo Developers. Device-identifying values held by Feed are encrypted at rest and scoped to your organization. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard/devices`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `feed:read`. - `/dashboard/devices` uses `/api/widget` with the `record.list` template and `feed.devices.list` data source. - `/dashboard/media` uses `/api/widget` with the `record.detail` template and `feed.media.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Treat Topolo Device Platform as a retained product family with several separately deployable surfaces rather than a single product runtime. The callable platform service registry exposes feed delivery through the stable `topolo-feed` service slug, with `feed` retained as a registry alias; feed analytics remains a device telemetry surface, and feed media assets are served from TopoloFeed's `topolo-feed-assets` R2 bucket. The former Nodo host-acquisition Pages site is retired and no longer has an active Cloudflare deployment. ## Failure Modes - the product family is documented as if it were one coherent app - retired host-acquisition copy is reintroduced as an active runtime surface - provisioning, feed delivery, and analytics responsibilities are conflated - lifecycle maturity is overstated for the provisioning branch - mobile app catalog ownership is reintroduced as a separate device-platform API instead of staying in Developers ## Debugging Start with `/systems/topolo-device-platform`, then identify the exact sub-surface before debugging or documenting behavior. ## Use It Open [Topolo Device Platform](https://feed.topolo.app) for the human product surface. The [system handbook](/systems/topolo-device-platform) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-device-platform --json topolo actions --service topolo-device-platform --json topolo actions capabilities --service topolo-device-platform --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-device-platform) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Device Platform and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled this page against `apps/TopoloFeed` `origin/staging` `e157a439a3f2` on 2026-08-01 after reading `a2ac292` (`feat: close Feed enterprise privacy and device auth`). Recorded per-device credentials with single-device rotation and at-rest protection of device-identifying values. No surface boundary changed. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloFeed` `origin/staging` `d6b87c5d8495` on 2026-07-27. - Reconciled this page against `apps/TopoloFeed` `origin/staging` `d57457e4594f` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Consolidated TopoloFeed browser administration onto the live shared-shell operator console on 2026-07-11 and removed the undeployed mock API Explorer from the workspace build graph. - Reconciled workspace verification on 2026-06-28 against apps/TopoloFeed commits through f50a827; reviewed 211 commits since 2026-05-27, including f50a827 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 88626af Stop blocking startup on i18n readiness; 4d3f170 Adopt canonical Topolo typography; 2073b78 Lazy load Feed startup surfaces. - Retired the Nodo host-acquisition Cloudflare Pages surface on 2026-05-10. - Moved TopoloFeed media delivery onto the Topolo-named `topolo-feed-assets` R2 bucket on 2026-04-23. - Added the Nodo host-acquisition website surface at `nodo.topolo.io` on 2026-05-02. - Added the TopoloFeed asset host and clarified TopoloFeed/TopoloMDM ownership boundaries on 2026-04-23. - Re-established the TopoloFeed production hosts and callable `feed` service registry entry on 2026-04-23. - Registered retained mobile surfaces as first-party Topolo app records in Developers on 2026-04-23. - Moved mobile app catalog ownership from the standalone AppLibrary API into Topolo Developers on 2026-04-22. - Folded the feed API and operator UI into `apps/TopoloFeed` on 2026-04-22 - Promoted the retained app-library, feed API, and feed runtime repos to first-class `PlatformApplications/*` roots on 2026-04-22 - Renamed the feed runtime container to `TopoloFeed` on 2026-04-22 - Added canonical device-platform coverage and retired repo-local cluster docs on 2026-03-30 ## Topolo Director Canonical URL: https://docs.topolo.app/applications/director Public overview of Director as the Topolo workspace for proof-driven product demo runbooks and readiness gates. ## What It Is Topolo Director helps authenticated teams coordinate proof-driven demo runbooks, chunked human recording, production readiness gates, raw-footage archive handoff, timed script review, voice-render requests, and narration for product walkthroughs. When a script should sound like a specific person, Director is the intended consumer of Agent-owned person profiles for writing and speaking style rather than the owner of reusable likeness data. Teams can separate initiatives into Director workspaces and create recording projects inside each workspace. A project can start with a complete ordered shot plan and then create one or more recording sessions without exposing projects from another workspace. ## Architecture Director runs as a Cloudflare Worker application with Topolo Auth protecting its workspace API. The shared platform chrome displays the first-party short name `Director`, while the browser title and social metadata use the canonical `Topolo Director` name. The app persists demo runbooks, required active inputs, human presenter cues, recording sessions, recording chunks, chunk takes, take trash/flag/R2 sync status, composition manifests, proof gates, narration review, timed script-pass events, voice-render requests, and bridge readiness in its own Director data store and exposes a TopoloOne widget for live workspace visibility. The workspace is split into focused sections for overview, sessions, runbooks, proof gates, script review, and capture readiness rather than a single long dashboard. Runbook queue, detail, create, and edit are separate workspace states, with edit persistence for runbook metadata and required active inputs. The paired local bridge writes raw capture manifests to a local `bytes/director/raw` spool so teams can opt into automatic TopoloBytes sync and backup without losing the original take. Each runbook declares the inputs it needs from Mac screen, camera, phone mirror, OBS, and CTA overlay, and scenes must use only those active inputs rather than naming unavailable devices. The bridge can install polished `Director | ...` OBS scenes for available inputs, mirror camera self-view sources, clean the local Mac desktop non-destructively for screen recordings, and show or hide animated Topolo lower-third, CTA, and voice-cue overlays when those graphics are active for the runbook. Human notes and teleprompter prompts are written as off-record sidecar files and are not opened in the captured browser or added to OBS scenes. Human take controls are shown as dockable native floating macOS glass panels with a movable script strip, separately movable icon controls, capture hiding, adaptive color profiles, automatic review remux, and immediate playback. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces - production: `https://director.topolo.app` - staging: `https://director.stg.topolo.us` ## API Reference Director exposes a curated authenticated API for workspace-scoped recording project creation and retrieval, project session creation, runbook management, session tracking, off-record session prompter retrieval, chunk/take cataloging, take selection/trash/flag/R2 sync state, composition manifest generation, recorded-session script passes, cue approval, voice-render request tracking, proof-gate review, bridge pairing, bridge heartbeat, and the TopoloOne widget. Workspace discovery itself comes from the platform-owned Auth catalog. ## Auth and Permissions Director resolves its concrete Topolo Auth app id at runtime from service slug `topolo-director`, with workspace read and write permissions in the Auth service catalog. ## Data Ownership Director owns demo runbook, required-input, off-record human cue, recording-session, recording-chunk, chunk-take, take-control state, media-catalog, composition-manifest, proof-gate, narration, voice-render request, bridge-readiness, and recording-event content for its workspace surface. The paired local bridge owns raw footage and off-record prompter/control sidecars until the workspace enables TopoloBytes backup. R2 sync requests are queued as take state until a TopoloBytes/R2 binding performs the transfer. Agent owns reusable person-profile writing/speaking metadata, Voice owns reusable voice-profile metadata, and generated voice audio stays with the downstream Nexus voice provider until an output path is attached for Director review. Topolo Auth owns user identity, organization context, service entitlement, and the company-admin boundary for using another human user's likeness. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/runbooks`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/overview` uses `/api/director/status` with the `record.detail` template and `director.status.detail` data source. - `/runbooks` uses `/api/director/runbooks` with the `record.list` template and `director.runbooks.list` data source. - `/runbooks/:runbookId` uses `/api/director/runbooks/:runbookId` with the `record.detail` template and `director.runbooks.detail` data source. - `/proof` uses `/api/director/status` with the `workflow.inbox` template and `director.proofGates.list` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Director deploys from `apps/TopoloDirector` to the production and staging Worker routes documented in `/systems/topolo-director`. ## Failure Modes - missing Auth session - missing service entitlement - incorrect environment Auth proxy configuration - stale service catalog snapshot - expired bridge pairing or offline local bridge - blocked proof gates before export - source proof explicitly blocked for a source used by the runbook - runbook scenes that reference inputs not selected for that runbook - selected person profile is not owned by the subject user or available to an organization admin - narration cues not approved before voice render - voice render marked ready without output evidence - teleprompter or operator notes placed inside a captured display - floating take controls run without macOS screen-capture hiding enabled - composition blocked by a missing or blocked selected take ## Debugging Use `/systems/topolo-director` for deployment detail and the internal handbook for route-level debugging notes. ## Use It Open [Topolo Director](https://director.topolo.app) for the human product surface. The [system handbook](/systems/topolo-director) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-director --json topolo actions --service topolo-director --json topolo actions capabilities --service topolo-director --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-director) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Director and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloDirector` `origin/staging` `d82379409330` on 2026-07-27. - Reconciled this page against `apps/TopoloDirector` `origin/staging` `adabc3049ce3` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Added Director workspace resource discovery, workspace-scoped recording projects, complete initial shot plans, and project session creation on 2026-07-14. - Reconciled workspace verification on 2026-06-28 against apps/TopoloDirector commits through 9b24a23; reviewed 321 commits since 2026-05-14, including 9b24a23 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 98349a3 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); d3d78af Adopt canonical Topolo typography; e986fbd Split Director startup bundle. - Updated the public Director overview on 2026-05-06 for short platform chrome naming plus favicon, app manifest, Apple touch icon, and PNG Open Graph assets. - Updated the public Director overview on 2026-05-13 for runtime Auth app identity resolution from slug `topolo-director`. - Added public application coverage on 2026-05-06 so Director is represented consistently in Docs, the systems registry, and the generated Auth catalog. - Updated the public Director overview on 2026-05-06 for the D1-backed production workflow and local bridge contract. - Updated the public Director overview on 2026-05-06 for raw Bytes archive handoff and record-first narration. - Updated the public Director overview on 2026-05-06 for recorded-session script passes and cue approval. - Updated the public Director overview on 2026-05-06 for persisted voice-render requests. - Updated the public Director overview on 2026-05-06 for optional camera and phone source readiness. - Updated the public Director overview on 2026-05-06 for runbook-owned active input declarations and clean scene naming. - Updated the public Director overview on 2026-05-06 for off-record human cues and teleprompter sidecars. - Updated the public Director overview on 2026-05-06 for bridge-controlled OBS scene, mirror, and CTA overlay controls. - Updated the public Director overview on 2026-05-06 for focused workspace sections. - Updated the public Director overview on 2026-05-06 for separate runbook queue, detail, create, and edit states. - Updated the public Director overview on 2026-05-06 for bridge-installed polished OBS scenes and operator overlays. - Updated the public Director overview on 2026-05-06 for local bridge desktop hygiene. - Updated the public Director overview on 2026-05-07 for chunked human recording, take cataloging, and composition manifests. - Updated the public Director overview on 2026-05-07 for off-record operator controls, take trash/flag metadata, and R2 sync queue state. - Updated the public Director overview on 2026-05-07 for native floating macOS take controls. - Updated the public Director overview on 2026-05-07 for compact glass-style macOS take controls. - Updated the public Director overview on 2026-05-07 for dockable macOS take controls with color profiles. - Updated the public Director overview on 2026-05-07 for split movable icon controls and automatic review playback. - Updated the public Director overview on 2026-05-07 for Agent/Auth likeness authorization rather than GDPR-style Consent. - Updated the public Director overview on 2026-05-07 for Agent person-profile consumption in script generation. - Reverified the public Director overview on 2026-05-12 for the opaque Auth app id and current app repository path. ## TopoloDocs Canonical URL: https://docs.topolo.app/applications/docs Canonical documentation, system registry, and machine-readable launch evidence for the Topolo Platform. ## What It Is TopoloDocs is the canonical multi-tenant documentation application and registry surface for the Topolo Platform. It publishes product documentation, internal system handbooks, system registry metadata, Auth catalog snapshots, and launch-readiness evidence, while giving each organization isolated documentation workspaces. ## Architecture The signed-in product is a React/Vite TypeScript application using the shared Topolo app shell, workspace model, Auth client, and localization provider. A TypeScript API Worker owns workspace-scoped spaces, documents, immutable versions, locale variants, full-text retrieval, and publication. The platform handbook builds from checked-in Markdown and JSON under `apps/web/src/content` into public and gated static routes plus agent-readable manifests. The original Topolo platform corpus belongs to organization `org_topolo_platform`. Repository content remains its authored source of truth and is projected into an Auth-owned Docs workspace as locked, revisioned documents. Public platform pages are published from the `topolo-platform` space; internal handbooks and system registry contracts are projected into separate gated spaces. This preserves the public documentation website while making the corpus available through the same multi-tenant search, version, citation, and automation architecture as other Docs workspaces. ## Runtime Surfaces - public docs at `https://docs.topolo.app` - development docs at `https://docs.topolo.dev` - staging docs at `https://docs.stg.topolo.us` - signed-in documentation workspaces at `/app` - public tenant publications at `/s/:space/:document` - system registry entries under `src/content/systems` - generated machine output for system and security evidence - source-backed public capability coverage at `/reference/source-coverage` and `/machine/source-coverage.json`, including exact action schemas, valid examples, route-implementation evidence, verification steps, and recovery guidance - public `/llms.txt` index and `/llms-full.txt` retrieval corpus - full-text Docs search across headings, metadata, and page bodies - command-palette search over documents in the space you are reading, matching titles and summaries instantly and published body text behind them - browsable public action contracts backed by Topolo Developers - Auth app manifest `app_topolo_docs` ## API Reference TopoloDocs exposes workspace-scoped authoring, version, localization, search, grounded-answer, and publication APIs under `/api/docs/*`; public published-document reads and space search under `/api/public/docs/*`, whose space manifest carries the configurable section hierarchy readers and agents navigate by; and generated machine-readable system output under `/machine/systems/:system.json`. Its complete 34-action surface is published through Topolo Developers, including the `docs:write`-protected `platform_corpus.sync` projection action fixed to the canonical platform organization, the section-hierarchy actions that reorder a space's sections and file documents into them, and the anonymous `public_search.query` action, which searches one published space and matches published versions only. ## Auth and Permissions Public docs and explicitly published tenant snapshots are readable without application auth. Authoring APIs require a verified organization, a canonical Docs workspace, and the relevant Docs permission; tenant identifiers are derived from trusted Auth context rather than accepted from request bodies. ## Data Ownership TopoloDocs owns tenant spaces, sections, documents, immutable versions, locale variants, publication state, documentation content, system metadata, generated docs evidence, and validation output. It does not own product runtime data for the applications it documents. ## Deployments TopoloDocs deploys through the standard CloudControl-backed development, staging, and production paths. Bare `npm run deploy` is disabled; use `npm run deploy:development`, `npm run deploy:staging`, or `npm run deploy:production`. ## Failure Modes - system registry drift from Auth app catalog manifests - launch-readiness evidence out of date with checked-in systems - production or publication gates bypassed before docs validation - generated machine output stale after catalog or registry changes ## Debugging Run `npm run validate` first, then run the relevant security/privacy gate profile. For app registry issues, compare `src/content/systems/*.json` with the Auth app catalog manifests. ## Use It Open [TopoloDocs](https://docs.topolo.app) for the human product surface. The [system handbook](/systems/topolo-docs) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-docs --json topolo actions --service topolo-docs --json topolo actions capabilities --service topolo-docs --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-docs) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloDocs and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reverified canonical source discovery on 2026-08-01. Generated fleet evidence excludes local clones by matching each checkout directory to its configured origin repository and currently covers 51 canonical repositories, 64 systems, 1,832 actions, 34 shared packages, and 1,688 exports. - Converted TopoloDocs to the canonical multi-tenant React/Vite and TypeScript Worker architecture on 2026-07-28, with shared shell, Auth, workspace, and i18n contracts plus isolated authoring, search, localization, and publication data paths. - Assigned the original platform corpus to `org_topolo_platform` on 2026-07-28 and added its revisioned projection into the canonical Auth-owned Docs workspace, with public, internal, and system-registry spaces and a fully published 27-action catalog. - Added canonical source-backed coverage on 2026-07-28 for 64 systems, 51 repositories, 1,820 unique actions, 34 shared packages, and 1,670 package exports. Public output is visibility-filtered and strips secret names, database table details, test details, package manifests, and binding targets; internal system and package references retain the complete operator evidence. - Rebuilt Docs evidence on 2026-07-27 from all 63 registered systems and their canonical staging workspaces; added revisioned runtime/API snapshots, resolvable source-path gates, full-text search, public/internal `llms-full.txt`, browsable action discovery, practical usage examples for every public application guide, and explicit TopoloProvision coverage. - Reconciled this page against `system-apps/TopoloDocs` `origin/staging` `33239895a0d8` on 2026-07-25 after the fleet workspace-ownership documentation correction and a clean 179-document validation. - Reconciled this page against `system-apps/TopoloDocs` `origin/staging` `459193fd223f` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against system-apps/TopoloDocs commits through 9ebc732; reviewed 31 commits since 2026-06-26, including 9ebc732 docs: bump app-shell lazy route factory release; 24ccaa4 docs: record app-shell lazy route factory; 9a5cbde docs: add workspace docs audit; 03ec7ca docs: record app-shell route preloader. - Added first-class TopoloDocs system coverage on 2026-05-11 so Auth catalog validation can verify the Docs service boundary. ## Topolo Feed Canonical URL: https://docs.topolo.app/applications/feed Public overview of Topolo Feed in the Topolo application suite. ## What It Is Topolo Feed is part of the Topolo business application suite. It turns activity across your content feeds into analytics: impression and engagement summaries, device breakdowns, scheduled digests, and anomaly alerts when engagement moves unexpectedly. ## Architecture Topolo Feed runs on Topolo's platform and signs you in through Topolo Auth. Your feed analytics are scoped to your organization and workspaces. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The workspace is live at `https://feed.topolo.app`. ## API Reference Topolo Feed exposes its capabilities as Topolo actions — connecting sources, syncing activity, and reading summary, engagement, and device analytics — available through the Topolo SDK, CLI, and MCP surfaces. Alongside these it publishes privacy and device-credential actions: export or delete your organization's Feed data, and rotate a device's credential. ## Auth and Permissions Access requires a Topolo account. Sign in through Topolo Auth to reach your organization's feed analytics. ## Data Ownership Topolo Feed owns your feed sources and the analytics derived from their activity — impressions, engagement, device breakdowns, digests, and anomaly records — scoped to your organization. Personal and device-identifying values are encrypted at rest and bound to your organization, so they are not readable outside it. You can export everything Feed holds for your organization, or delete it, through the privacy actions. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard/devices`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `feed:read`. - `/dashboard/devices` uses `/api/widget` with the `record.list` template and `feed.devices.list` data source. - `/dashboard/media` uses `/api/widget` with the `record.detail` template and `feed.media.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Feed is available in production at `https://feed.topolo.app`. ## Failure Modes If a feed source cannot be reached, its latest sync is skipped and analytics reflect the last successful sync rather than showing stale data as current. ## Debugging If analytics look wrong, confirm the feed source is connected and syncing from the workspace settings. ## Use It Open [Topolo Device Platform](https://feed.topolo.app) for the human product surface. The [system handbook](/systems/topolo-device-platform) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-device-platform --json topolo actions --service topolo-device-platform --json topolo actions capabilities --service topolo-device-platform --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-device-platform) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Device Platform and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled this page against `apps/TopoloFeed` `origin/staging` `e157a439a3f2` on 2026-08-01 after reading `a2ac292` (`feat: close Feed enterprise privacy and device auth`). Added the customer-facing privacy and device-credential actions to API Reference and the at-rest protection statement to Data Ownership. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloFeed` `origin/staging` `d6b87c5d8495` on 2026-07-27. - Reconciled this page against `apps/TopoloFeed` `origin/staging` `d57457e4594f` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Consolidated Feed under the canonical Topolo Device Platform system identity on 2026-07-22. - Published overview on 2026-07-20. ## Topolo Flow Canonical URL: https://docs.topolo.app/applications/flow Public overview of Topolo Flow in the Topolo application suite. ## What It Is Topolo Flow is part of the Topolo business application suite. ## Architecture The application uses the shared Topolo shell and Topolo Auth boundary from the outset. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The scaffold baseline is live at `https://flow.topolo.app`. Staging mirrors it at `https://flow.stg.topolo.us` with a staging build that keeps Auth calls inside the staging installation. ## API Reference The generated API baseline exposes authenticated workspace routes under `/api/*` and validates requests through Topolo Auth. ## Auth and Permissions Signed browser and API requests use Topolo Auth through app id `app_GBCuKkHhnRXv`. ## Data Ownership Flow owns organization-scoped flow definitions and execution records. Nexus owns stored provider connections and their lifecycle status; Flow does not override that status when it supplies connection credentials and metadata. ## Mobile Experience The checked-in mobile experience contract is **published** in `native_capability` mode. Its fallback route is `/flows`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/flows` uses `/api/flows` with the `record.list` template and `flow.flows.list` data source. - `/flows/:id` uses `/api/flows/:id` with the `record.detail` template and `flow.flows.detail` data source. - `/runs` uses `/api/runs` with the `record.list` template and `flow.runs.list` data source. - `/runs/:id` uses `/api/runs/:id` with the `record.detail` template and `flow.runs.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments The scaffold baseline is live at `https://flow.topolo.app`. ## Failure Modes - service registration and app routing can drift while the product is still planned - organization-scoped data models are not implemented until domain work begins ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Flow](https://flow.topolo.app) for the human product surface. The [system handbook](/systems/topolo-flow) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-flow --json topolo actions --service topolo-flow --json topolo actions capabilities --service topolo-flow --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-flow) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Flow and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the Nexus connection-status ownership boundary against `apps/TopoloFlow` `origin/staging` `e4e6da045f87` on 2026-07-31. - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloFlow` `origin/staging` `53f367d8e0ad` on 2026-07-27. - Reconciled this page against `apps/TopoloFlow` `origin/staging` `c75288452658` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloFlow commits through d9d27ff; reviewed 344 commits since 2026-05-14, including d9d27ff chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); b82cc49 Adopt canonical Topolo typography; 6714eed Lazy load Flow startup routes; 5c4cfd6 Roll out ui-kit capture startup split. - Verified Flow staging origin isolation on 2026-04-30. - Deployed Worker/static-assets baseline to `https://flow.topolo.app` on 2026-04-23. - Scaffold generated on 2026-04-23 from `topolo apps scaffold`. ## Topolo Forecast Canonical URL: https://docs.topolo.app/applications/forecast Public overview of the forecasting product for cash-flow, P&L, KPI, and multi-scenario planning workflows. ## What It Is Topolo Forecast is the finance-planning surface for cash-flow forecasting, P&L analysis, KPI tracking, and multi-scenario modeling. ## Architecture The system combines a browser app, worker/API surface, shared domain logic, and shared UI packages under a Cloudflare-oriented deployment model. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces Use `/systems/topolo-forecast` for the current runtime inventory and host mapping. ## API Reference The current contract is curated in the docs platform rather than OpenAPI-backed. The main surface centers on forecasting models, scenarios, dashboard and KPI flows, and their Auth-protected runtime. Workspace reads come from the shared Topolo workspace service rather than a Forecast-specific `workspaces.get` action. Forecast retains only its finance-specific workspace operations, including active-scenario selection and guarded archive behavior. ## Auth and Permissions Forecast relies on Topolo Auth for user and org access. Worker bearer requests are validated through Topolo Auth before Forecast-owned workspace authorization runs. Authenticated workspace membership no longer bypasses the Forecast service permission checks used by the worker routes, and the worker no longer ships a development-only auth escape hatch. Forecast resolves the concrete environment-specific app id from the `topolo-forecast` service slug at runtime. The Worker uses Auth `/api/services/by-slug/topolo-forecast` before service-scoped Auth validation, widget responses, API-key management, and seed validation; the browser uses the same slug lookup before service-scoped Auth handoff and API headers. Forecast browser callbacks delegate one-time `sso_code` redemption to the shared `@topolo-io/auth-client` package. Direct bearer-token callback URLs and `/sso?token=` bridge routes are not supported. The browser keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal page reload should return to Forecast instead of looking logged out while cookie refresh catches up. Forecast now also normalizes any missing Auth role claim to `member` during browser bootstrap, matching the canonical platform role ladder. The authenticated Forecast web workspace uses the shared `TopoloAppShell` for shell chrome, account menu, app launcher, command palette, theme toggle, sidebar collapse, and account-menu BugFix reporting. Forecast-specific workspace switching stays inside additive account-menu actions, and public landing, login, callback, and shared-workspace pages do not mount standalone BugFix controls. ## Data Ownership Forecast owns financial models, scenarios, KPI calculations, and related planning data. Workspace URLs and creation are organization-scoped. Two different organizations can use the same workspace slug, while each organization still keeps its own unique workspace URLs internally. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard/workspace`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `settings:read`, `settings:write`, `forecasts:read`, `forecasts:write`, `workspace:read`, `workspace:write`, `workspace:delete`. - `/dashboard/workspace` uses `/api/widget` with the `record.detail` template and `forecast.widget.get` data source. - `/chart-of-accounts` uses `/api/v1/:workspace/coa` with the `record.list` template and `coa.get` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Forecast deploys as a web-plus-worker application with shared packages and a Cloudflare deployment path. The current worker data bindings use `forecast-db` in production and `forecast-db-staging` in staging. The browser app keeps the shared BugFix reporter UI available from the authenticated account menu while skipping the optional startup enabled-status probe. ## Failure Modes - stale Forecast metadata causes service-registration or environment drift - web and worker deployments disagree on the active environment contract - Auth configuration is bypassed or incorrectly stubbed ## Debugging Start with `/systems/topolo-forecast`, then verify the current environment contract and Auth wiring for the failing scenario flow. ## Use It Open [Topolo Forecast](https://forecast.topolo.app) for the human product surface. The [system handbook](/systems/topolo-forecast) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-forecast --json topolo actions --service topolo-forecast --json topolo actions capabilities --service topolo-forecast --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-forecast) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Forecast and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the reachable public-share route and platform-owned workspace boundary through `apps/TopoloForecast` `origin/staging` `a91d74ee55b6` on 2026-07-29. The unused `/v1/shared/:token/info` route is no longer part of the runtime contract. - Reconciled the platform-owned workspace read boundary and removed the retired Forecast `workspaces.get` declaration on 2026-07-28. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloForecast` `origin/staging` `233dfcde7985` on 2026-07-27. - Reconciled this page against `apps/TopoloForecast` `origin/staging` `853d715584c7` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloForecast commits through ae7551c; reviewed 98 commits since 2026-06-18, including ae7551c chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); ddb7f84 Split Forecast startup auth bundle; cc8e31f Adopt canonical Topolo typography; 4a55ce9 Split Forecast shell startup bundle. - Removed Forecast's standalone public-route BugFix control on 2026-05-12 so Improve Topolo remains an authenticated account-menu action. - Removed hardcoded concrete app ids from Forecast web and worker runtime paths on 2026-05-13 so app identity is resolved through Auth by slug per environment. - Migrated the authenticated Forecast web workspace to the shared `TopoloAppShell` on 2026-04-25. - Enabled same-tab browser session restore by default on 2026-04-23 so Forecast reloads remain signed in after successful Auth handoff or refresh. - Corrected Forecast role normalization on 2026-04-24 so missing Auth role claims resolve to `member` during browser session bootstrap. - Removed a non-critical Forecast browser startup warning on 2026-04-20 by skipping the optional BugFix enabled-status probe. - Removed Forecast worker app-local JWT validation on 2026-04-18 so authenticated API requests depend on Topolo Auth validation before Forecast workspace authorization. - Removed the Forecast `/sso?token=` browser bridge on 2026-04-18 so `/auth/callback` now relies on the shared Topolo browser auth client for code redemption - Removed the remaining Forecast worker auth bypasses on 2026-04-11 so protected routes and workspace resolution always depend on Topolo Auth or API-key-backed access - Replaced the remaining legacy Forecast D1 resource names on 2026-04-11 so the deployed worker metadata now points at `forecast-db` and `forecast-db-staging` - Standardized Forecast worker permission enforcement on 2026-04-10 so the authenticated API no longer treats workspace membership alone as a sufficient grant - Fixed Forecast's shared auth callback handoff on 2026-04-07 so production `/auth/callback` consumes callback tokens directly again and no longer fails immediately on app-switch entry - Restored Forecast's shared suite app launcher on 2026-04-07 so the production app no longer opens the legacy `Topolo Suite` modal - Standardized the Forecast-facing labels and frontend API defaults on 2026-04-07 so the live app routes against `forecast-worker-production` instead of the retired legacy host - Added canonical Topolo Forecast coverage and retired repo-local Forecast docs on 2026-03-30 ## Topolo Forms Canonical URL: https://docs.topolo.app/applications/forms Public overview of Topolo Forms, the Topolo general forms and public submission application. ## What It Is Topolo Forms is the Topolo application for intake, waitlist, request, and structured form submission workflows. Operators manage form definitions in the authenticated workspace and can publish public submission links when needed. ## Architecture The application uses the shared Topolo shell and Topolo Auth for authenticated workspace access. A Cloudflare Worker serves the workspace, public published form routes, and API surface, backed by an app-owned D1 database. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces - Shared landing page at `https://forms.topolo.app/` - Shared login page at `https://forms.topolo.app/login` - Shared auth callback at `https://forms.topolo.app/auth/callback` - Authenticated workspace at `https://forms.topolo.app/` once signed in - Public collector routes under `https://forms.topolo.app/public/:slug`, with visible form-loading content during direct-route startup - Authenticated admin APIs under `/api/forms/*` - Public submission APIs under `/api/public/forms/:slug*` ## API Reference The current production v1 exposes: - `GET /api/health` - `GET /api/bootstrap` - `GET/POST /api/forms` - `GET/PATCH/DELETE /api/forms/:id` - `GET /api/forms/:id/submissions` - `POST /api/forms/:id/crm-sync` - `GET /api/forms/:id/summary` - `GET /api/public/forms/:slug` - `POST /api/public/forms/:slug/submissions` ## Auth and Permissions Authenticated browser and API requests use Topolo Auth after resolving the `topolo-forms` service identity dynamically from its canonical slug. Signed-out operators land on the shared Topolo landing and login screens before entering the workspace. Public form routes do not require authentication and expose only published form definitions plus submission acceptance. Operators can manually sync a form's submissions into TopoloCRM after Forms dynamically resolves the `topolo-crm` service identity; CRM still enforces contact-write access for that operator. ## Data Ownership Topolo Forms stores organization-scoped form definitions and submissions in its own D1 database. Public submission routes write only into the owning organization for the published form slug being collected. CRM sync is explicit and manual; public submission does not automatically create CRM contacts, and submissions without a valid email are reported as skipped rather than sent to CRM. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/forms`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/forms` uses `/api/forms` with the `record.list` template and `forms.forms.list` data source. - `/forms/:id` uses `/api/forms/:id` with the `record.detail` template and `forms.forms.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Forms is deployed on Cloudflare Workers with Workers Static Assets at `https://forms.topolo.app`, with shared landing, login, and callback pages on the browser surface plus the authenticated forms workspace after sign-in. Staging mirrors it at `https://forms.stg.topolo.us` with staging Auth, Notify, and public-base bindings. ## Failure Modes - a published slug points operators or respondents to the wrong intake workflow - public submission routes expose draft form definitions or private workspace metadata - manual CRM sync is run by an operator without CRM contact-write access or against submissions without valid email addresses - general form collection drifts into a different product boundary before the core intake and waitlist flows are solid ## Debugging - use the internal handbook for operational detail - verify the system registry entry before deployment or service-registration changes - smoke the published form GET and POST routes after deploy when submission behavior changes ## Use It Open [Topolo Forms](https://forms.topolo.app) for the human product surface. The [system handbook](/systems/topolo-forms) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-forms --json topolo actions --service topolo-forms --json topolo actions capabilities --service topolo-forms --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-forms) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Forms and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified `apps/TopoloForms` `origin/staging` `b1704efe8709` on 2026-07-31: direct public and embedded collector routes render visible form-loading content while their lazy route loads. Reconciled this page with the canonical dynamic `topolo-forms` and `topolo-crm` service-slug identity resolution. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloForms` `origin/staging` `265599bbaff5` on 2026-07-27. - Reconciled this page against `apps/TopoloForms` `origin/staging` `22631b545d7e` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloForms commits through 6ee941e; reviewed 432 commits since 2026-05-14, including 6ee941e chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 870cacd Stop blocking startup on i18n readiness; 75cd70c Adopt canonical Topolo typography; a241e5a Roll out ui-kit capture startup split. - Verified Forms staging origin and Notify binding isolation on 2026-04-30. - Updated the public Forms overview on 2026-05-13 for runtime Auth app identity resolution from slugs `topolo-forms` and `topolo-crm`. - Implemented the first production v1 with D1-backed forms, public collectors, submission capture, and submission summary on 2026-04-23. - `npm run typecheck` - `npm test` - `npm run build` - `npm run validate` in TopoloDocs ## Topolo Home Canonical URL: https://docs.topolo.app/applications/home Public overview of Topolo Home in the Topolo application suite. ## What It Is Topolo Home is part of the Topolo personal application suite. ## Architecture The application uses the shared Topolo landing page, shared login page, auth callback handling, and shared Topolo shell from the outset. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The planned production host is `https://home.topolo.app`, with public entry at `/`, sign-in at `/login`, and callback completion at `/auth/callback`. ## API Reference The generated API baseline exposes authenticated personal and household routes under `/api/*` and validates requests through Topolo Auth. ## Auth and Permissions Signed browser and API requests use Topolo Auth through app id `app_hE6HBldVzjth`, supplied to the Worker as `APP_ID` rather than resolved through a runtime Auth slug lookup. ## Data Ownership The generated baseline has no durable domain data yet. Future data must be household-scoped at the backend boundary. ## Deployments The planned production host is `https://home.topolo.app`. Development and staging mirror the scaffold at `https://home.topolo.dev` and `https://home.stg.topolo.us`. ## Failure Modes - service registration and app routing can drift while the product is still planned - household-scoped data models are not implemented until domain work begins ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Home](https://home.topolo.app) for the human product surface. The [system handbook](/systems/topolo-home) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-home --json topolo actions --service topolo-home --json topolo actions capabilities --service topolo-home --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-home) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Home and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Reconciled this page against `apps/TopoloHome` `origin/staging` `31487e5a043b` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloHome commits through 5daa1ba; reviewed 12 commits since 2026-06-26, including 5daa1ba chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 8dd7491 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); efced3c Stop blocking startup on i18n readiness; 8195702 Adopt canonical Topolo typography. - Scaffold generated on 2026-05-06; first-party scaffolding now uses restricted `topolo-platform apps scaffold`. ## Topolo Insights Canonical URL: https://docs.topolo.app/applications/insights Public overview of Topolo Insights in the Topolo application suite. ## What It Is Topolo Insights is part of the Topolo business application suite. ## Architecture The application uses the shared Topolo shell and Topolo Auth boundary from the outset. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The scaffold baseline is live at `https://insights.topolo.app`. Development and staging mirrors run at `https://insights.topolo.dev` and `https://insights.stg.topolo.us`. ## API Reference The generated API baseline exposes authenticated workspace routes under `/api/*` and validates requests through Topolo Auth. ## Auth and Permissions Signed browser and API requests use Topolo Auth through app id `app_DgbBMwWSIhmC`. ## Data Ownership The generated baseline has no durable domain data yet. Future data must be organization-scoped at the backend boundary. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard/workspace`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`. - `/dashboard/workspace` uses `/api/widget` with the `record.detail` template and `insights.workspace.summary` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments The scaffold baseline is live at `https://insights.topolo.app`, with development and staging mirrors at `https://insights.topolo.dev` and `https://insights.stg.topolo.us`. ## Failure Modes - service registration and app routing can drift while the product is still planned - organization-scoped data models are not implemented until domain work begins ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Insights](https://insights.topolo.app) for the human product surface. The [system handbook](/systems/topolo-insights) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-insights --json topolo actions --service topolo-insights --json topolo actions capabilities --service topolo-insights --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-insights) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Insights and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 1 published route(s) against `apps/TopoloInsights` `origin/staging` `4e0112a53082` on 2026-07-27. - Reconciled this page against `apps/TopoloInsights` `origin/staging` `0889a9660a89` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloInsights commits through 8bd9894; reviewed 12 commits since 2026-06-26, including 8bd9894 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); f7b5ee0 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); b54cb65 Stop blocking startup on i18n readiness; c65a8d8 Adopt canonical Topolo typography. - Deployed Worker/static-assets baseline to `https://insights.topolo.app` on 2026-04-23. - Scaffold generated on 2026-04-23 from `topolo apps scaffold`. ## Topolo Inventory Canonical URL: https://docs.topolo.app/applications/inventory Public overview of Topolo Inventory, the Topolo item, location, and stock movement workspace. ## What It Is Topolo Inventory is the Topolo application for managing item records, locations, stock adjustments, and low-stock visibility inside an authenticated operational workspace. ## Architecture The application uses the shared Topolo shell and Topolo Auth for authenticated operator workflows. A Cloudflare Worker serves the workspace and authenticated API surface, backed by an app-owned D1 database. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces - Shared landing page at `https://inventory.topolo.app/` - Staging mirror at `https://inventory.stg.topolo.us/` - Shared login page at `https://inventory.topolo.app/login` - Shared auth callback at `https://inventory.topolo.app/auth/callback` - Authenticated workspace at `https://inventory.topolo.app/` once signed in - Authenticated inventory APIs under `/api/items`, `/api/locations`, `/api/movements`, and `/api/dashboard` ## API Reference The current production v1 exposes: - `GET /api/health` - `GET /api/bootstrap` - `GET/POST /api/items` - `GET/PATCH/DELETE /api/items/:id` - `GET/POST /api/locations` - `GET/POST /api/movements` - `GET /api/dashboard` ## Auth and Permissions Authenticated browser and API requests use Topolo Auth through app id `app_hmvjbv3ZxDnh`, supplied to the Worker as `APP_ID` rather than resolved through a runtime Auth slug lookup. Signed-out operators land on the shared Topolo landing and login screens before entering the workspace. There are no public unauthenticated data collection routes in the v1 inventory product. ## Data Ownership Topolo Inventory stores organization-scoped items, locations, and stock movement rows in its own D1 database. Quantity on hand is derived from the movement ledger rather than edited as a separate mutable balance. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/items`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/items` uses `/api/items` with the `record.list` template and `inventory.items.list` data source. - `/items/:id` uses `/api/items/:id` with the `record.detail` template and `inventory.items.list` data source. - `/locations` uses `/api/locations` with the `record.list` template and `inventory.locations.list` data source. - `/locations/:id` uses `/api/locations/:id` with the `record.detail` template and `inventory.locations.list` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Inventory is deployed on Cloudflare Workers with Workers Static Assets at `https://inventory.topolo.app`, with shared landing, login, and callback pages on the browser surface plus the authenticated inventory workspace after sign-in. ## Failure Modes - inventory balances drift if writes bypass the stock movement ledger - archived items continue accepting stock movement rows - item or location identifiers drift from the D1 uniqueness guarantees enforced in migrations ## Debugging - use the internal handbook for operational detail - verify the system registry entry before deployment or service-registration changes - smoke dashboard, item, location, and movement routes after deploy when stock logic changes ## Use It Open [Topolo Inventory](https://inventory.topolo.app) for the human product surface. The [system handbook](/systems/topolo-inventory) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-inventory --json topolo actions --service topolo-inventory --json topolo actions capabilities --service topolo-inventory --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-inventory) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Inventory and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloInventory` `origin/staging` `f543e06d9fa7` on 2026-07-27. - Reconciled this page against `apps/TopoloInventory` `origin/staging` `41593f200928` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloInventory commits through 37f35f7; reviewed 322 commits since 2026-05-14, including 37f35f7 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 9a642d7 Stop blocking startup on i18n readiness; f96c326 Fix Inventory required workspace loading; 06d8ca4 Adopt canonical Topolo typography. - Implemented the first production v1 with D1-backed items, locations, stock movements, derived quantity-on-hand, and low-stock dashboard on 2026-04-23. - `npm run typecheck` - `npm test` - `npm run build` - `npm run validate` in TopoloDocs ## TopoloLearn Canonical URL: https://docs.topolo.app/applications/learn Public overview of the Topolo-native multi-brand learning platform for branded education businesses, cohort delivery, assessment, and certification. ## What It Is TopoloLearn is the Topolo application for branded learning businesses. It combines a public site, member portal, learn account studio, assessment workflows, evidence packs, certificates, and customer seat management in one multi-brand product. ## Architecture TopoloLearn is split across: - a web application for operator, studio, public, and member experiences - a Worker API for Learn account-safe reads, writes, and verification routes - D1, R2, KV, and queues for learning, submission, certificate, and published-brand state The first-party `learn.topolo.app` homepage uses the shared Topolo landing-page package and Auth-managed landing config. Authenticated visitors can continue directly from the landing CTA or `/login` into Learn's application home. Learn account brand hostnames use Learn's product runtime to render brand-owned public pages, programme detail, offers, faculty, FAQ, and member entrypoints. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. For Learn, the platform workspace id is also the brand id. Learn owns the learning and presentation data attached to that id, while Auth remains the sole owner of its workspace name, slug, and default status. ## Runtime Surfaces - `apps/TopoloLearn/apps/web` - `apps/TopoloLearn/apps/api` - Topolo Auth for identity, session validation, and app-switcher metadata ## API Reference The initial curated API surface lives in `apps/TopoloLearn/apps/api/src/index.ts` and currently includes runtime resolution, operator and studio overview, learner overview, submission review, certificate issuance, and public verification routes. ## Multi-Brand Model TopoloLearn is a platform product rather than a single-customer LMS. - one TopoloLearn deployment serves multiple Auth organization-owned Learn accounts - each learn account can own multiple brands - each brand can publish its own public and member hosts - all application data is learn account-scoped and brand-aware ## Core Feature Areas - branded public websites - branded member portals - learn account studio for theme, programme, cohort, assessment, and certificate management - artefact submissions with versioning - rubric-based review flows - evidence pack assembly - certificate issuance and public verification - customer seat packs and assignment ## Demo Learn account The seed data uses a neutral customer-academy demo account to exercise cohort-heavy certification flows without hardcoding TopoloLearn around any real business. ## Auth and Permissions TopoloLearn uses Topolo Auth for identity and session state, with browser login handoff and callback-code redemption delegated to the shared Topolo Auth client. API bearer requests are validated by Topolo Auth before product-specific learn account and brand roles are enforced inside the Learn worker, so authenticated users only reach the operator, studio, or member surfaces allowed by their TopoloLearn role assignments. Improve Topolo is exposed through the shared authenticated account menu rather than standalone header or command-palette controls. ## Data Ownership TopoloLearn owns learn account, Learn-specific brand configuration, programme, cohort, assessment, submission, evidence-pack, certificate, and customer-seat state. Topolo Auth remains authoritative for user identity, organization context, and app-scoped workspace identity. ## Mobile Experience The checked-in mobile experience contract is **published** in `native_capability` mode. Its fallback route is `/programmes`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `studio:read`, `studio:write`, `certificates:write`, `operator:read`, `settings:read`, `runtime:read`. - `/programmes` uses `/api/studio/programmes` with the `record.list` template and `learn.programmes.list` data source. - `/programmes/:id` uses `/api/studio/programmes/:id` with the `record.detail` template and `learn.programmes.detail` data source. - `/assessments` uses `/api/studio/assessments` with the `record.list` template and `learn.assessments.list` data source. - `/assessments/:id` uses `/api/studio/assessments/:id` with the `record.detail` template and `learn.assessments.detail` data source. - `/cohorts` uses `/api/studio/cohorts` with the `record.list` template and `learn.cohorts.list` data source. - `/customers` uses `/api/studio/customers` with the `record.list` template and `learn.customers.list` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments TopoloLearn currently defines a web Worker surface plus a Worker API surface with Cloudflare D1, R2, KV, and queue bindings declared in the CloudControl manifest. The staging mirror uses `https://learn.stg.topolo.us` and `https://learn-api.stg.topolo.us`; staging web builds run with staging Auth/API origin injection and a staging-only rewrite for shared UI defaults that would otherwise emit production origins. ## Failure Modes - hostname resolution can fail when a brand has no published domain mapping - authenticated studio or member routes can fail when Topolo Auth session validation is unavailable - certificate issuance should remain blocked until evidence-pack and assessment gating rules are satisfied ## Debugging Start with the internal handbook at `/internal/apps/topolo-learn`, then inspect `apps/api/src/index.ts`, the D1 migration set, and the CloudControl manifest for route, schema, and deployment shape. ## Use It Open [TopoloLearn](https://learn.topolo.app) for the human product surface. The [system handbook](/systems/topolo-learn) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-learn --json topolo actions --service topolo-learn --json topolo actions capabilities --service topolo-learn --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-learn) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloLearn and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the platform-owned workspace model through `apps/TopoloLearn` `origin/staging` `6975b471c881` on 2026-07-28. Learn no longer stores an independently writable copy of the workspace name, slug, or default state. - Verified the native_capability mobile experience contract and its 6 published route(s) against `apps/TopoloLearn` `origin/staging` `16a07b42aa87` on 2026-07-27. - Reconciled this page against `apps/TopoloLearn` `origin/staging` `0aa8b66a4bb9` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloLearn commits through 83b9837; reviewed 97 commits since 2026-06-18, including 83b9837 Use shared Studio UI primitives in Learn; 73a525b Split Learn cohort studio sections; 727a860 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 98765dd Use shared ui kit for Learn surfaces. - Moved visible Learn Improve Topolo access fully into the shared account menu on 2026-05-12. - Verified Learn staging origin isolation on 2026-04-30. - Verified on 2026-04-18 that Learn API bearer validation requires Topolo Auth validation before Learn-local role enforcement. - Delegated Learn web login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18. - Verified on 2026-04-17 that authenticated visitors route from the shared Learn landing entrypoint into the application home instead of re-opening login. - Verified on 2026-04-16 that the first-party Learn platform homepage uses the shared landing page while learn account brand pages remain Learn-owned runtime pages. - Added the initial public overview for TopoloLearn on 2026-04-08. - Verified the doc against the new application scaffold, shared auth integration points, and TopoloLearn system entry on 2026-04-08. ## TopoloMDM Canonical URL: https://docs.topolo.app/applications/mdm Public overview of the device-management cluster spanning the MDM API, operator console, and mobile scaffold. ## What It Is TopoloMDM is the device-management cluster for registration, polling, realtime and Firebase wake events, fleet control, operator console workflows, an Android DPC, and an early mobile client scaffold. ## Architecture The repo currently spans a worker/API surface, a browser console, a workspace-scoped realtime event hub, a retryable notification outbox with scheduled offline detection, and a mobile scaffold with uneven maturity across those layers. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces Use `/systems/topolo-mdm` for the current API host and repo inventory. ## API Reference The active route surface centers on device registration, polling, realtime operator events, device command wakeups, Firebase token registration, commands, fleet inspection, admin API-key operations, and operator helper endpoints. MDM also publishes typed enrollment, command-result, compliance, profile-change, and offline facts through the Developers notification catalog and TopoloNotify. ## Auth and Permissions Device registration and polling use public network routes, but enrollment now requires a server-issued one-time enrollment token and continuing device poll/status calls require the issued device credential. Device realtime wakeups and Firebase token registration use the same issued credential and only trigger the existing `/poll` path. Operator and admin actions rely on Topolo Auth. Protected MDM API bearer-token requests validate through Auth and do not accept locally decoded JWT claims from a Worker secret. Browser console JWTs validate under the console service, while API-key requests remain scoped to the API service. The console and API resolve those Auth service boundaries from the `topolo-mdm` and `topolo-mdm-api` service slugs at runtime rather than embedding fixed app ids in browser or worker code. The operator console now uses the shared Topolo cookie-refresh auth client for browser sessions. The operator console browser callback accepts only Auth one-time `sso_code` handoffs on `/auth/callback`, delegates exchange to the shared Auth client, and no longer exposes direct-token callback or public SSO debug routes. ## Data Ownership TopoloMDM owns workspace-scoped device state, command queues, realtime fleet-event fanout, notification outbox/incident markers, operator console state, and related fleet-control records. ## Mobile Experience The checked-in mobile experience contract is **published** in `native_capability` mode. Its fallback route is `/devices`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `devices:read`, `policies:read`, `apps:read`. - `/devices` uses `/api/devices` with the `record.list` template and `mdm.devices.list` data source. - `/device-profiles` uses `/api/device-profiles` with the `record.list` template and `mdm.deviceProfiles.list` data source. - `/device-profiles/:id` uses `/api/device-profiles/:id` with the `record.detail` template and `mdm.deviceProfiles.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments TopoloMDM deploys as a cluster rather than a single polished product surface: worker API, console, Android DPC, and mobile scaffolding move at different speeds. TopoloProvision QR/R2 APK builds remain the production Android Enterprise enrollment lane. Google Play internal testing builds are available for sales and demo installs, but they run as normal Android demo sessions until a device is enrolled through QR or another Android Enterprise provisioning path. Current Android DPC builds call the live `mdm.topolo.app/api` surface through the console Worker/API service binding. Firebase Cloud Messaging is a wake channel for enrolled Android devices; commands still come from the authenticated polling endpoint. Installable app catalog metadata is read from the Developers-owned `developers.topolo.app/api/apps` route, which now includes Topolo Feed, Topolo Provision, and the 22 retained Topolo Mobile Android APKs as R2-backed installable rows served from `apk.topolo.app`. Topolo Provision and Topolo MDM Mobile are now first-party mobile app records under the Topolo Technology workspace in Developers, while the MDM repo remains the runtime/code owner. ## Failure Modes - mobile or console maturity is overstated compared with the actual repo surface - Google Play demo installs are mistaken for enrolled device-owner MDM devices - authenticated control flows are confused with public device registration flows - realtime command wakeups are treated as command execution instead of a trigger for the authenticated `/poll` path - Firebase wake delivery is configured without the matching Android app values or worker service-account secrets - Developers-owned package-catalog metadata is mistaken for core MDM API ownership - enrollment QR payloads point at stale TopoloProvision APK URLs, checksums, or expired enrollment tokens - enrolled devices miss the initial registration call during Android provisioning and only reach the worker through command polling without a valid enrollment token ## Debugging Start with `/systems/topolo-mdm`, then separate API, console, realtime, Android DPC, Firebase wake, mobile-scaffold, and Developers-owned app-catalog issues before debugging deeper. For QR enrollment failures, verify that the referenced TopoloProvision APK URL returns `application/vnd.android.package-archive`, that the payload checksum matches the served APK bytes, and that the QR was generated from a fresh authenticated enrollment session. If a Play-installed app is being evaluated, confirm it shows demo mode and do not expect kiosk/device-owner control until QR enrollment. If enrollment completes but the console remains empty, inspect the tenant-scoped `TOPOLO_STATE` keys and confirm the device either registered through `/register` or was recovered by the first `/poll` request with the one-time enrollment token. If command latency is high, verify the worker `TENANT_EVENTS` binding, operator `/events` bearer WebSocket, device `/device-events` `X-Device-Secret` handshake, and FCM token registration before tuning polling. ## Pre-April Scope Freeze As of 2026-04-29 (run `run_3a14d172049a`): - **Live implemented surfaces:** `topolo-mdm-api` and `topolo-mdm-console`. - **Operationally real but partial:** `apps/mobile/mdm` (authenticated session + realtime event wiring exists, but it is not a full production client workflow yet). - **Ownership/coordination lanes:** `TopoloProvision` APK enrollment and Android artifact metadata are production-owned by this cluster for runtime behavior, while broader catalog ownership and long-lived mobile artifact operations live through `Topolo Developers` (`https://developers.topolo.app/api/apps`). - **Out of scope for pre-April lane:** new feature expansion, major UI redesigns, and re-platforming beyond documented API/console parity fixes. ## Use It Open [TopoloMDM](https://mdm.topolo.app) for the human product surface. The [system handbook](/systems/topolo-mdm) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-mdm --json topolo actions --service topolo-mdm --json topolo actions capabilities --service topolo-mdm --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-mdm) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloMDM and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 3 published route(s) against `apps/TopoloMDM` `origin/staging` `627ad3b7f1d5` on 2026-07-27. - Reconciled this page against `apps/TopoloMDM` `origin/staging` `9a12af430300` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Published the eight app-owned MDM notification contracts on 2026-07-20, backed by durable enrollment, command, compliance, profile, and scheduled offline transitions with retryable delivery through TopoloNotify. - Reconciled workspace verification on 2026-06-28 against apps/TopoloMDM commits through 4ec9479; reviewed 374 commits since 2026-05-14, including 4ec9479 Remove MDM devices bottom scroll padding; fadbd64 Restore MDM device table scroll on collapse; bf8ae92 Clamp MDM devices scroll after row collapse; 12ab1fe chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile). - Hardened enrollment-session Durable Object migrations on 2026-06-28 so QR session creation stays idempotent across existing workspace state. - Finalized pre-April TopoloMDM scope freeze (live console+API, partial mobile scaffold, externalized app-catalog ownership via Developers) on 2026-04-29. - Published TopoloProvision core `1.2.172` to `apk.topolo.app` and switched MDM enrollment and install-package APK references to that host on 2026-04-23. - Exposed all 22 retained Topolo Mobile Android APKs to MDM through the Developers-owned `/api/apps` catalog on 2026-04-23. - Registered Topolo Provision and Topolo MDM Mobile as first-party Developers mobile app records on 2026-04-23. - Repointed MDM install-package catalog defaults to the Developers-owned `/api/apps` catalog on 2026-04-22. - Hardened MDM enrollment on 2026-04-22 so QR payloads carry server-issued enrollment tokens, registered devices receive per-device credentials, and authenticated debug routes redact device secrets. - Added Firebase Cloud Messaging wake delivery on 2026-04-22 so enrolled TopoloProvision devices can wake the existing authenticated poll path while backgrounded. - Aligned MDM API public references to the live `mdm-api.topolo.app` host on 2026-04-29. - Added TopoloProvision Google Play internal-testing readiness on 2026-04-22 so sales/demo installs are available without changing the QR enrollment authority. - Added realtime MDM events on 2026-04-22 so authenticated operator mobile sessions refresh from WebSocket events and enrolled TopoloProvision v1.2.169 devices wake the existing `/poll` worker as soon as commands are queued. - Corrected MDM enrollment QR payloads on 2026-04-22 so the console and mobile scaffold reference a live TopoloProvision APK URL with matching file and signature checksums. - Added first-poll registration recovery on 2026-04-22 so a provisioned device can enter the fleet if Android provisioning interrupted the initial DPC registration call. - Tightened Android provisioning on 2026-04-22 so the QR waits for DPC policy compliance and the compliance activity registers the device before setup completes. - Split MDM API validation for browser JWTs and API-service credentials on 2026-04-20 so the authenticated console can load device data without post-login 401 polling. - Moved MDM console/API app identity to runtime Auth slug resolution on 2026-05-13 so the deployed code keeps the console and API service boundary without hardcoded app ids. - Removed the MDM API worker's residual local `JWT_SECRET` handoff on 2026-04-18 so protected bearer-token requests validate through Auth. - Verified on 2026-04-18 that the MDM console browser callback delegates `sso_code` exchange to the shared Auth client instead of carrying console-local protocol logic - Verified the MDM console browser callback on 2026-04-17 so it completes sign-in through one-time `sso_code` exchange and removes public legacy SSO/debug callback routes - Standardized TopoloMDM console browser auth on the shared Topolo auth client on 2026-03-31 - Added canonical TopoloMDM coverage and retired repo-local MDM docs on 2026-03-30 ## Topolo Messages Canonical URL: https://docs.topolo.app/applications/messages Public overview of Topolo Messages in the Topolo application suite. ## What It Is Topolo Messages is part of the Topolo business application suite. It is a channel-agnostic business messaging surface: manage conversations, contacts, campaigns, templates, and automations in one place, with external channels (such as WhatsApp) connected behind it. ## Architecture Topolo Messages runs on Topolo's platform and signs you in through Topolo Auth. Your conversations and campaigns are scoped to your organization. External channels are connected to your workspace and appear through the same messaging surface. Provider callbacks terminate at Topolo Nexus. Nexus owns the provider credential, external identity and status, and supplies a stable connection reference to Messages. Messages accepts only a signed, short-lived relay whose tenant, app, resource, connection, and body context all match; it does not expose a second provider-ingress path. The channel connection flow registers the environment-specific Messages relay target with Nexus and fails closed if that target is not configured. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The workspace is live at `https://messages.topolo.app`. ## API Reference Topolo Messages exposes its capabilities as Topolo actions — managing conversations and contacts, building and launching campaigns, creating templates and automations, and connecting channel numbers — available through the Topolo SDK, CLI, and MCP surfaces. Its semantic-search action searches only within the caller's verified workspace and keeps plaintext message bodies out of the vector index. ## Auth and Permissions Access requires a Topolo account. Sign in through Topolo Auth to reach your organization's messaging workspace. ## Data Ownership Topolo Messages owns your conversations, contacts, campaigns, templates, and automations, scoped to your organization. Connected channels remain owned by their providers; Nexus reads their status and Messages stores only the stable Nexus reference plus its own inbox labels and defaults. Restricted message content uses context-bound application-layer encryption. Messages reads through primary, previous, and available Secrets Store key copies during rotation, and a scheduled decrypt canary detects both missing durable-store availability and key drift using row identities without exposing message content or ciphertext. Workspace- and protection-domain-scoped data keys carry explicit epochs and are wrapped by the Messages root key. Exact staging API version `1b2900be-917d-4a55-8316-339bad6431b4` proved its durable Secrets Store key available and decrypted 101 sampled protected rows with no exceptions. The current runtime accepts only `tp2`; the retired envelope reader and rewrite job are no longer shipped. Workspace owners can export their Messages data or erase its content, and aged operational records move to private archive storage under defined retention windows. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/conversations`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `inbox:read`, `campaigns:manage`. - `/conversations` uses `/api/messages/conversations` with the `record.list` template and `messages.conversations.list` data source. - `/conversations/:id` uses `/api/messages/conversations/:id` with the `record.detail` template and `messages.conversations.detail` data source. - `/contacts` uses `/api/messages/contacts` with the `record.list` template and `messages.contacts.list` data source. - `/contacts/:id` uses `/api/messages/contacts/:id` with the `record.detail` template and `messages.contacts.detail` data source. - `/campaigns` uses `/api/messages/campaigns` with the `record.list` template and `messages.campaigns.list` data source. - `/campaigns/:id` uses `/api/messages/campaigns/:id` with the `record.detail` template and `messages.campaigns.detail` data source. - `/templates` uses `/api/messages/templates` with the `record.list` template and `messages.templates.list` data source. - `/templates/:id` uses `/api/messages/templates/:id` with the `record.detail` template and `messages.templates.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Messages is available in production at `https://messages.topolo.app`. The staging deployment at `https://messages.stg.topolo.us` was reverified on 2026-08-01 across its web, API, and dispatch Workers. Provider identity and status columns are absent from the sender table, the signed relay persists stable Nexus context, and both the Messages and Nexus public health endpoints are healthy. ## Failure Modes If a connected channel is disconnected, sends to that channel pause until it is reconnected rather than failing silently. ## Debugging If messages are not delivering, confirm the channel number is connected from the workspace settings. ## Use It Open [TopoloMessages](https://messages.topolo.app) for the human product surface. The [system handbook](/systems/topolo-messages) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-messages --json topolo actions --service topolo-messages --json topolo actions capabilities --service topolo-messages --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-messages) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloMessages and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Deployed the no-compatibility `tp2` cutover on 2026-08-01 at exact source `455c50f1d4fd842bfc0db64eade249c56e3dfab0`. The next scheduled run reported a healthy 101-row canary with durable-store continuity and no legacy migration event. Both staging organizations passed their own semantic search and received 403 on the other organization's exact workspace, with request IDs preserved. - Deployed the registered Nexus relay target and reverified end-to-end staging ingress on 2026-08-01 at Messages source `8cd3ffebfd23261e0bd1464d3b23083ffd35ffd8` and Nexus source `84fe731656363b303a7d3d8f924107f9f0d1bfab`. A correctly signed event reached the expected workspace and was processed by the webhook queue; invalid signatures and unknown phone-number routes failed closed. - Deployed and reverified stable Nexus connection ownership on staging on 2026-08-01 at Messages source `409ba6047985ecf22ec490038329aaed31b820bc` and Nexus source `98670312d18757d2232e454cee827222f0a39b76`. - Inspected staging source `4b6bac511da584dfd34acd5ad2e7ad3517d38ca4` on 2026-07-31 for hierarchical envelope keys and workspace-scoped semantic search. The runtime proof that remained open at that snapshot is closed by source `455c50f1d4fd842bfc0db64eade249c56e3dfab0` above. - Closed that runtime gap on 2026-08-01: scheduled maintenance and the decrypt canary were healthy on 101 protected rows, and a two-organization semantic-search probe returned owner 200 with request-ID roundtrip while denying the other organization 403 on the exact same workspace. - Verified the fail-closed key-lifecycle canary on 2026-07-30 against exact staging source `4a2792fb8e9610c11e0680d8ceb19b0e88616cf9`; the runtime correctly withheld a healthy lifecycle result while the durable store key was unavailable. - Added store-backed key continuity and a scheduled identity-only decrypt-drift canary for protected message content on 2026-07-28. - Verified the native_capability mobile experience contract and its 8 published route(s) against `apps/TopoloMessages` `origin/staging` `3f6338f8ef4a` on 2026-07-27. - Consolidated the retired WhatsApp-specific documentation identity into this channel-agnostic canonical Messages page and verified the three-target staging deployment on 2026-07-22. - Converged provider ingress on Nexus and verified the signed replay-bounded Messages relay on 2026-07-22. - Added application-layer content protection, defined retention, and workspace export/erasure controls on 2026-07-24. - Verified Auth-projected workspace isolation and the complete live export/erasure lifecycle on 2026-07-24. - Published overview on 2026-07-20. ## Topolo Nexus Canonical URL: https://docs.topolo.app/applications/nexus Public overview of Nexus as the platform gateway for metered provider and application usage across Topolo applications. ## What It Is Topolo Nexus is the platform gateway for metered provider and application usage across Topolo applications. It centralizes provider access, usage logging, app attribution, and budget-aware routing instead of each application managing provider keys independently or writing usage counters in isolation. ## Architecture Nexus ships as a Cloudflare-backed gateway plus dashboard. The gateway now fronts typed AI, email, and payment provider operations rather than acting as a raw passthrough proxy. Platform-default vendor credentials are now persisted inside Nexus rather than resolved directly from product apps. Nexus worker `PLATFORM_*` secrets now act only as the bootstrap source for missing platform-default rows in the Nexus `provider_credentials` store. Provider connections receive stable Nexus references. Product apps keep their business objects and labels while Nexus keeps credentials, provider identifiers and status, and provider-owned verification decisions. For Meta messaging, Nexus also verifies the external webhook and signs the complete tenant, app, resource, connection, and body context delivered to the receiving product. Verification uses the encrypted, environment-specific credential for the exact target application; a webhook is not routed until one active application credential verifies it. Nexus also keeps provider display names, avatar/profile links, scopes, expiry, and terminal lifecycle state. Trusted provider callbacks can resolve an account by provider subject through an app-bound lookup, and only an explicit OAuth reconnect can reactivate a disconnected or deauthorized connection. ## Runtime Surfaces - Nexus gateway worker - Nexus dashboard - D1-backed usage, key, provider-credential, and preference storage - generic application usage ingestion for API-backed apps The Nexus dashboard uses `TopoloAppShell` from the shared Topolo UI Kit for its authenticated workspace, including the standard sidebar, account menu, command palette, top utility controls, direct light/dark theme toggle, app launcher, BugFix reporter entrypoint, and first-party app icon treatment. Nexus preferences stay inside the dashboard, while identity/security settings hand off to Topolo Admin's `/security/user` route. Current production host split: - dashboard origin: `https://nexus.topolo.app` - gateway worker origin: `https://nexus-api.topolo.app` The isolated staging mirror uses `https://nexus.stg.topolo.us` for the dashboard and `https://nexus-api.stg.topolo.us` for the gateway. Staging dashboard builds inject staging Auth, Admin, dashboard, and gateway origins so browser bundles do not drift back to production. ## API Surface The current gateway route families are: - `/api/ai` - `/api/email` - `/api/payments` - `/api/keys` - `/api/provider-credentials` - `/api/usage` - `/api/preferences` - `/api/apps` - `/api/models` - `/platform/usage/events` - `/platform/integrations/connections/*` The `/api/provider-credentials` surface is reserved for the platform-default credential management flow and is not a general end-user API. The image-generation preference surface returns the stored organization preference when one exists; otherwise it returns the Nexus platform image baseline, currently OpenAI GPT Image 2 (`gpt-image-2`) with Google Nano Banana 2 (`gemini-3.1-flash-image-preview`) as the managed-provider fallback. Runtime image generation follows that order and can use the on-platform Cloudflare image route as an operational safety net if managed external providers reject before returning an image. OpenAI image metering uses provider-reported GPT image usage when available and otherwise falls back to a bounded size/quality estimate rather than deriving billable output tokens from returned image payload length. The allowed image catalog includes OpenAI GPT Image 2 and Google Nano Banana model ids for product UIs that expose permission-gated per-request overrides. The model-governance surface exposes the configured platform defaults, organization overrides, recent usage by model, lifecycle status, source verification freshness, and upstream candidate models observed from provider catalogs. Nexus runs this catalog sync from the gateway Worker schedule and restricts manual refresh to platform super admins. ## API Reference Nexus currently uses curated docs coverage rather than a published OpenAPI surface in TopoloDocs. The live contract is centered on typed route families for AI completions and generations, email send operations, payment operations, generic app usage events, plus usage, key, preference, and app metadata routes. Stripe price creation accepts either an existing product ID or Stripe product data supplied by the calling app. `/platform/usage/events` is the generic application usage route for API-backed apps and platform services. It records stable app, organization, optional user, meter, event, unit, and request-id attribution so Nexus reporting can show how much each user and organization consumes even when the event is not a direct provider call. Image-generation defaults stay in Nexus and provider rate-limit responses are retryable so requests can continue through the configured AI fallback chain before a product surfaces failure. Scoped hard-stop spend limits are restricted to organization owners, organization super admins, and platform super admins. The dashboard and API use Nexus-provided option metadata for allowed app, user, capability, use-case, provider, and model values instead of accepting arbitrary scope text. ## Standardization Rule Topolo applications should use Nexus for outbound calls to metered third-party APIs and for generic API/application usage where attribution by organization, user, and application matters. This rule is aimed at vendor APIs such as AI, messaging, enrichment, similar usage-billed integrations, and platform API-call metering. It does not automatically apply to webhook verification secrets, OAuth client secrets, or infrastructure credentials. ## Current Rollout State The current standardization slice now covers: - Roadmapper AI generation and notification email delivery - BugFix AI generation and validation - Showcase generation and video-analysis flows - Socialize text, image, trend, email, and billing flows - Topolo Social Studio planning and generation flows - TopoloOne checkout creation and webhook-side subscription retrieval - TopoloPay outbound order, refund, status, and cancellation operations - TopoloCommerce server-side voice transcription and voice-intent resolution through the Commerce worker using trusted service-context attribution ## Auth and Permissions Nexus relies on Topolo Auth bearer tokens or trusted service-to-service credentials so provider usage can be attributed to the correct organization and user context. The Auth API-key scope catalog for Nexus mirrors its permission surface across app metadata, provider-credential management, and usage telemetry. The Nexus dashboard keeps the auth surface in a loading state during initial cookie-backed session rehydration on refresh or app-switch entry so transient auth events do not flash the user back to the login screen or public landing page. That refresh path depends on Topolo Auth allowing the `X-Topolo-Auth` and `X-App-ID` headers on the cross-origin `/refresh` preflight from `nexus.topolo.app`. The dashboard browser login handoff and one-time `sso_code` callback redemption delegate to the shared `@topolo-io/auth-client` package. Direct bearer-token callback URLs and `/sso?token=` bridge routes are not supported. The service-context path requires: - `Authorization: Bearer ` - `X-Nexus-Organization-Id` - `X-Nexus-App-Id` when the service JWT slug does not fully identify the calling app - optional `X-Nexus-User-Id` User-driven routes should forward the caller's bearer token instead. Service workers should mint Auth service JWTs and carry organization, app, and optional user attribution in request headers. Fixed-org payment surfaces such as TopoloOne marketing checkout and TopoloPay set `X-Nexus-Organization-Id` to the Auth organization with slug `topolo`. TopoloNotify uses the same platform-sender pattern for default transactional email, including recovery-email verification, so `topolo.app` and `stg.topolo.us` sender-domain ownership stays attached to the Topolo platform organization rather than each customer organization. Credential resolution order is now: 1. organization BYOK stored in Nexus `api_keys` 2. Nexus-managed org override in `provider_credentials` 3. Nexus-managed platform default in `provider_credentials` The platform-default mutation surface is restricted to Auth users whose role is `platform_super_admin` in the Auth `admin` organization. The raw secret is write-only and is never returned by the API or dashboard after save. Platform-default credentials use a fixed internal identifier per provider inside Nexus and are not user-renameable. Active platform-default credentials collapse by default in the dashboard and can be expanded when the platform admin needs to rotate or disable them. ## Data Ownership Nexus owns platform-managed provider keys, usage events, cost attribution, model lifecycle metadata, upstream catalog observations, and provider preference routing. Product applications continue to own their own business objects and domain data. ## Deployments Nexus deploys as its own gateway and dashboard surfaces. Applications integrating with Nexus should only need Nexus connection configuration plus their normal user or service auth context, not raw vendor keys for supported integrations. The current service-context rollout uses Auth-issued service JWTs for backend-to-backend calls, while bearer-token forwarding remains the standard for user-driven routes. The current bootstrap path still reads Nexus worker `PLATFORM_*` secrets so missing platform-default rows can be seeded into `provider_credentials`, but product apps should not read or hold those provider secrets themselves. ## Failure Modes - application bypasses Nexus and calls a provider directly - provider key exists only in an app environment and not in Nexus - missing app, organization, request, or delegated-user attribution results in incomplete usage reporting - gateway/provider policy is not aligned with product expectations ## Debugging Start with the gateway health and usage surfaces, then confirm the application is routing outbound provider calls through the gateway worker origin instead of the dashboard origin or directly to the vendor and that its bearer token or Auth service-JWT context headers are present. ## Use It Open [Topolo Nexus](https://nexus.topolo.app) for the human product surface. The [system handbook](/systems/topolo-nexus) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-nexus --json topolo actions --service topolo-nexus --json topolo actions capabilities --service topolo-nexus --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-nexus) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Nexus and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Deployed app-bound Meta webhook credentials and the validated product-relay registration contract on staging on 2026-08-01 at source `84fe731656363b303a7d3d8f924107f9f0d1bfab`, dashboard version `10c406d9-d809-4900-8ece-5be89a353d0c`, and gateway version `781bd834-a555-4590-8de4-299033ff0d71`. A signed staging event completed the Nexus-to-Messages relay; invalid signatures failed with HTTP 401 and unknown numbers did not cross a tenant boundary. - Added and staging-verified app-bound provider lookup, provider profile projection, and explicit reconnect reactivation on 2026-08-01; Socialize now consumes that contract as its sole connected-provider authority. - Deployed and verified the stable Meta connection-reference and context-bound relay contract on staging on 2026-08-01 at source `98670312d18757d2232e454cee827222f0a39b76` and gateway version `566bbef4-e791-44bc-89fa-85bc52a0f6f6`. - Reconciled docs freshness on 2026-06-28 against topolo-platform through 20653c79; latest commit reviewed was 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap), with recent context 20653c79 feat(auth): bulk availability + app_id-mapping endpoints (seed subrequest cap); 61117a0d feat(app-shell): add lazy component factory; d8784cfa feat(app-shell): add canonical lazy route factory. - Added generic platform usage-event coverage on 2026-06-04 so API-backed apps and platform services can report app, organization, optional user, meter, unit, and request-id attribution through Nexus instead of maintaining local counters. - Added model-governance and catalog-monitoring coverage on 2026-05-07 so Nexus can show configured defaults, recent model usage, lifecycle risk, source health, and newly observed upstream model candidates. - Restricted scoped hard limits to owner/super-admin managers on 2026-05-02 and changed the dashboard to use Nexus-provided searchable scope options. - Treated raw provider HTTP 429 image-generation responses as retryable on 2026-05-02 so Nexus continues through the configured AI fallback chain. - Recast Nexus onto the explicit platform-role model on 2026-04-24 so platform-default provider credentials require Auth `platform_super_admin`; backend service access now comes from Auth-issued service JWTs rather than Nexus-local service-client rows. - Restored the Nexus dashboard Auth data proxy and direct shell theme toggle on 2026-04-19 so the app launcher resolves Auth `/api/*` service endpoints and the shell exposes light/dark mode - Split the Nexus account menu on 2026-04-19 so Nexus preferences stay in the dashboard while identity/security settings hand off to Topolo Admin `/security/user`. - Synced the Nexus Auth API-key scope catalog on 2026-04-19 so live D1 rows and generated seed SQL mirror the Nexus permission contract. - Removed the Nexus dashboard `/sso?token=` browser bridge and app-local login URL construction on 2026-04-18 so login handoff and `/auth/callback` code redemption now rely on the shared Topolo browser auth client - Retired dedicated static Nexus service tokens in favor of Auth-issued service JWTs for unattended service delivery. - Clarified the production Nexus host split on 2026-04-12 so application integrations use the gateway worker origin for `/api/*` traffic instead of the dashboard origin - Verified against the current Nexus gateway route surface, platform-key dashboard behavior, provider-credential storage model, service-token rollout, app migration state, and Auth refresh-header contract on 2026-03-31 ## TopoloOne Canonical URL: https://docs.topolo.app/applications/one Public overview of the TopoloOne dashboard, worker-backed growth surfaces, and the public developer-acquisition funnel. ## What It Is TopoloOne is the unified operational dashboard for managing services, API keys, application access, and platform-level workflows across Topolo applications, plus the public growth surface for pricing, demos, waitlists, launch content, and developer-program acquisition. ## Architecture TopoloOne is split between the dashboard web application and the routing worker that serves the production hostname and worker-backed APIs. The authenticated dashboard now acts as the complete application hub for the organization. It uses the same Auth-owned store catalog as the embedded app switcher, but separates quick access from discovery: dashboard home keeps installed apps, favorites, widgets, and launch workflows close to hand, while `one.topolo.app/store` owns categories, collections, search, app detail, install/open state, and admin install audiences. The public `topolo.io/app-store` route and the embedded launcher both consume the same canonical store contract. Embedded launcher discovery cards use whole-card primary actions: installable apps open their audience chooser directly, while other discovery cards hand off into the authenticated TopoloOne store detail route instead of rendering a redundant nested open button. Discovery cards also keep square app-icon tiles across density changes and suppress the generic `Available` pill unless there is a meaningful pricing or state label to show. Launcher density preferences are Auth-owned alongside favorites and hidden apps, so compact, comfortable, and large tile modes follow the signed-in user across first-party applications instead of being local to one app. Auth service surface metadata is the boundary for this hub: only launchable application surfaces appear as apps, while APIs, runtimes, internal services, and organization-internal developer distributions stay out of the launcher and store discovery views. Live workspace still follows a platform rule that every launchable application in the active catalog must have a visible TopoloOne dashboard presence. Apps with a native `/api/widget` endpoint can expose richer live data, and TopoloOne backfills a fallback overview card for the rest so the workspace selector is not limited to the small native-widget subset. The marketing and signup payment surfaces in the repo now route outbound Stripe checkout and subscription retrieval through Topolo Nexus while keeping Stripe webhook signature verification and subscription-state persistence local to the worker boundary. The public pricing story uses a moving early-customer seat price with packages layered on top: the current public base rate is $8.56 per seat per month, the free workspace exposes free apps through a $1/year verification subscription, paid bundles add 3, 5, 10, or every paid Topolo app while keeping free apps included, third-party app installs and customer-built apps stay unlimited through the Topolo app store, earlier customers already locked lower rates, the next paid seat price rises after each paid signup, and high-usage services stay separate from the subscription. Public pricing also sets the honest comparison against mature specialist SaaS: Topolo does not claim every app is feature-for-feature equivalent today, and instead positions each app around the 80% of key functionality most teams need while every signup funds more tokens, app coverage, and product expansion. Locked paid rates remain fixed while the subscription is active, except for external cost changes such as taxes, payment processing, infrastructure, AI, messaging, storage, or other provider costs. The marketing project also serves as the acquisition layer for changelog/content publishing, the curated `/apps` portfolio, developer-program overview content, and future SEO campaign or child-site surfaces, as long as those routes stay aligned to the canonical host and deployment contract. Public developer CTAs now continue into the separate `TopoloDevelopers` application at `developers.topolo.app/signup`, and the public `/developers/apply` plus `/developers/submit-app` pages now act as SEO-preserving handoff pages instead of primary system-of-record forms. The public marketing site dogfoods Topolo Consent through the `topolo-one-marketing` Consent project: the local analytics banner still owns the visual UI, but accept/decline decisions sync through the Topolo Consent web SDK with the staging build pointing at `https://consent.stg.topolo.us`. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. The shared shell remains visible while that workspace state resolves. Loading, an unavailable stored selection, a catalog error, and an account with no assigned workspace each produce a clear recovery surface rather than a blank dashboard. ## Runtime Surfaces TopoloOne currently ships two public runtime surfaces: the dashboard at `https://one.topolo.app` and the primary marketing/growth site at `https://topolo.io` (with `https://www.topolo.io` as the canonical www alias). The legacy `https://one.topolo.io` hostname is redirect-only and permanently redirects each path and query to `https://topolo.io`. The authenticated developer portal at `https://developers.topolo.app` is a separate application. ## API Reference Use the per-app API page at `/reference/apps/topolo-one` for the current client contract and Auth-backed request paths. ## Auth and Permissions TopoloOne does not own service scope definitions, bindable resource catalogs, or API-key interaction logic. Its organization-wide API-key page uses the shared multi-application management screen, which reads metadata from Topolo Auth and submits key-management changes back to Auth. Its dashboard browser session flow now uses the shared Topolo cookie-refresh auth client and resolves the canonical TopoloOne Auth service from the `topolo-one` service slug. Dashboard SSO callbacks delegate Auth `/sso/exchange` handling to the shared Auth client, so callback URLs carry one-time `sso_code` values rather than bearer tokens. The dashboard browser auth adapter does not expose a legacy `/sso?token=` handoff helper. Platform-wide API-key controls remain limited to Auth `platform_super_admin` and `platform_admin` users in the `admin` organization, while org-scoped super admins stay elevated only for organization-scoped dashboard management. Anonymous checkout and webhook-side payment flows use Nexus trusted service credentials rather than app-local Stripe API keys. These calls are attributed to the Auth organization with slug `topolo`, and the default gateway base URL is `https://nexus-api.topolo.app`. Paid TopoloOne checkout carries the selected package ID, package name, app allowance, locked base seat price, locked package seat price, and locked-rate caveat in Stripe metadata. The paid package IDs are `three`, `five`, `ten`, and `everything`; they define paid Topolo app access, while third-party app installs and customer-built apps remain open-ended through the Topolo app store. Legacy `core`, `growth`, and `business` IDs normalize into the new bundle model. The free workspace path uses a Stripe subscription checkout for a $1/year workspace verification, and completed free-workspace verification subscriptions are stored separately from paid subscription records so they do not move the paid-price curve. Restricted admin views for subscriptions and demo bookings now use server-issued session cookies instead of any client-visible password gate. Public developer CTAs hand users into `developers.topolo.app/signup`, where the shared Topolo browser auth client and Auth-owned developer-platform routes take over instead of a separate local account store. ## Data Ownership The dashboard owns its delivery and UI state, but the canonical API key scope and bindable-resource catalogs remain in Auth. Nexus owns the standardized outbound payment provider invocation used by the marketing site. Application catalog, service surface classification, pricing/discovery metadata, canonical store catalog/search/detail responses, launcher preferences, and user-level app assignment remain Auth-owned. TopoloOne presents and mutates those records through Auth APIs instead of storing a separate app marketplace state. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/apps`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `apps:read`, `dashboard:read`. - `/apps` uses `/api/apps` with the `record.list` template and `one.apps.list` data source. - `/apps/:slug` uses `/api/apps/:slug` with the `record.detail` template and `one.apps.detail` data source. - `/dashboard` uses `/api/widget` with the `record.detail` template and `one.dashboard.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments TopoloOne deploys as a dashboard web surface plus a worker-backed delivery/routing layer. Production serves the dashboard at `https://one.topolo.app`; staging serves the dashboard Worker asset surface at `https://one.stg.topolo.us` and keeps the staging dashboard Worker API on `https://api.one.stg.topolo.us`. The public marketing Worker also owns the curated app-portfolio routes, developer-program routes, waitlist, demo-booking, checkout, and acquisition-content delivery for `https://topolo.io` plus `https://www.topolo.io` (canonical www alias), and permanently redirects requests from the legacy `https://one.topolo.io` hostname to the matching path and query on `https://topolo.io`. The device-network marketing surface is not part of the launch apex messaging. The authenticated developer continuation lives in the separate `TopoloDevelopers` application on `https://developers.topolo.app`. ## Failure Modes - stale or incorrect hostname/bundle serving the dashboard - UI pointing at the wrong Auth route - selected app IDs not matching the Auth registry - missing Nexus service credentials or fixed org attribution on marketing checkout or payment routes - webhook verification and outbound payment API calls being treated as the same integration boundary - canonical host drift between `.app` and older `.io` URLs - broken marketing admin sessions due to missing worker-side admin secrets ## Debugging Start with `/systems/topolo-one` for the generated handbook and `/reference/apps/topolo-one` for the contract surface. For payment issues, distinguish local webhook-signature failures from outbound Nexus payment failures before checking Stripe. For public-site regressions, validate the canonical `https://topolo.io` URL, sitemap output, and worker `/health` route before assuming a content or design issue. ## Use It Open [TopoloOne](https://one.topolo.app) for the human product surface. The [system handbook](/systems/topolo-one) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-one --json topolo actions --service topolo-one --json topolo actions capabilities --service topolo-one --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-one) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloOne and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 3 published route(s) against `apps/TopoloOne` `origin/staging` `2b9910545c2c` on 2026-07-27. - Reconciled this page against `apps/TopoloOne` `origin/staging` `94b4ee0fb4eb` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Replaced TopoloOne's local API-key page on 2026-07-12 with the shared multi-application management screen while retaining platform-admin organization selection and Auth-backed service discovery. - Restored `one.topolo.io` on 2026-07-10 as a redirect-only hostname that returns a permanent `308` to the matching path and query on canonical `topolo.io`; no legacy marketing content is served from the alias. - Reconciled workspace verification on 2026-06-28 against apps/TopoloOne commits through 8e5c030e; reviewed 522 commits since 2026-06-18, including 8e5c030e chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); f8919c86 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 741ced14 Stop blocking startup on i18n readiness; 005c5bf3 Defer One error telemetry bundle. - Corrected embedded launcher tile sizing on 2026-04-26 so compact, comfortable, and large density modes now scale card spacing, typography, and action chrome together, while the selected density continues to persist through Auth-owned launcher preferences across first-party apps. - Wired the public TopoloOne marketing consent banner into Topolo Consent on 2026-05-06 so the `topolo-one-marketing` project records analytics, personalization, and advertising decisions through the Consent web SDK while the host site remains local-first if Consent is degraded. - Corrected the Topolo Staging dashboard split on 2026-04-29 so `one.stg.topolo.us` serves the dashboard Worker asset surface and the dashboard Worker API uses `api.one.stg.topolo.us`. - Preserved square discovery-card app icons and removed the redundant default `Available` state pill on 2026-04-26, so visible cards now only show a badge when pricing or a non-default state needs to be communicated. - Restored embedded launcher discovery-tile primary actions on 2026-04-26 so clicking the whole card now performs the canonical next step again, installable cards open their audience chooser directly, and non-installable discovery cards hand off to `one.topolo.app/store` instead of showing a redundant `Open Apps` footer button. - Consolidated the public `topolo.io/app-store`, authenticated `one.topolo.app/store`, and embedded launcher on 2026-04-25 so TopoloOne now presents one Auth-backed store contract instead of separate public, dashboard, and launcher discovery implementations. - Updated free workspace checkout on 2026-04-23 to use a $1/year verification subscription stored separately from paid subscriptions, while paid bundles continue to carry package metadata through Stripe/Nexus with locked-rate caveats visible on public pricing and checkout surfaces, third-party apps remain unlimited through the app store, and the pricing page now includes the honest 80%-and-growing comparison against traditional SaaS stacks - Set the current public early-customer seat price to $8.56 per month on 2026-04-23 while preserving earlier lower locked rates, the existing curve, cap, annual multiplier, and high-usage service separation - Promoted TopoloOne launch acquisition to `topolo.io` on 2026-04-23, retired the `one.topolo.io` alias on 2026-05-06, and excluded device-network marketing from the launch apex contract - Verified TopoloOne dashboard browser SSO on 2026-04-18 so launch and callback documentation matches the one-time `sso_code` handoff contract - Delegated TopoloOne dashboard callback exchange to the shared Auth client on 2026-04-18 and removed the remaining local token-bridge helper from the browser auth adapter - Enforced the TopoloOne live-workspace platform rule on 2026-04-25 so every launchable application in the active catalog now appears through either a native `/api/widget` endpoint or a TopoloOne fallback overview card, and the compact dashboard layout keeps the application hub visible higher in the viewport. - Corrected TopoloOne dashboard role normalization on 2026-04-24 so non-`admin`-tenant super admins keep owner-scoped dashboard access without receiving platform-wide selectors. - Upgraded the authenticated TopoloOne dashboard on 2026-04-16 into the full organization app hub, adding Auth-backed favorites, density, source grouping, available-app discovery, and admin install audiences for everyone, the current admin, or selected organization users - Restored the moving early-customer per-seat pricing model on 2026-04-10 so the public TopoloOne pricing surface again rewards early customers with a permanently lower locked rate while keeping high-usage services separate from base subscription seats - Converted the public `/developers/apply` and `/developers/submit-app` pages into signed-console handoff pages on 2026-04-13 so TopoloOne keeps discovery and acquisition while the actual developer records move into `developers.topolo.app` - Repointed the public developer CTA handoff to `developers.topolo.app/signup` on 2026-04-10 while keeping TopoloOne focused on overview and acquisition content rather than multiple public developer forms - Hardened the public marketing and pricing surface on 2026-04-10 so TopoloOne now serves worker-backed checkout, waitlist/demo flows, cookie-based admin sessions, and canonical marketing metadata from the same production delivery boundary - Refreshed the TopoloOne marketing portfolio on 2026-04-10 so `/apps` now reflects the wider Topolo application set with curated product media, and `/developers/*` now acts as the public intake surface for developer applications and app submissions - Standardized the TopoloOne dashboard browser auth layer on the shared Topolo auth client on 2026-03-31 - Verified against the current TopoloOne API key flow and Nexus-backed marketing payment routes on 2026-03-30 ## Topolo Pay Canonical URL: https://docs.topolo.app/applications/pay Public overview of the payment worker that handles orders, refunds, and payment operations. ## What It Is Topolo Pay is the payment-processing worker that powers order creation, refunds, admin payment operations, and related operational flows. ## Architecture The system is a worker-first payment surface with admin routes, webhook handling, and payment API operations. Inbound webhook verification remains domain-local. Outbound Stripe order creation, refunds, payment-status reads, and cancellation operations now route through Nexus. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces See `/systems/topolo-pay` for the runtime inventory and deployment entrypoints. ## API Reference Use `/systems/topolo-pay` plus the internal handbook for the current worker route inventory and the local-webhook versus Nexus-outbound payment boundary. ## Auth and Permissions Topolo Pay uses Topolo Auth and the shared platform middleware for admin permission checks on operational routes. Its outbound Nexus payment calls use trusted service credentials plus fixed attribution to the Auth organization with slug `topolo`. Pay app identity is resolved from the Auth-owned `topolo-pay` service slug at runtime; browser bundles must not embed production or staging `app_*` ids. Protected admin bearer-token authorization validates with Auth and does not accept locally decoded JWT claims from a Pay Worker secret. Admin browser login handoff and SSO callbacks delegate to the shared Topolo Auth client, including Auth `/sso/exchange` handling, so callback URLs carry one-time `sso_code` values rather than bearer tokens. Pay now also normalizes any missing Auth role claim to `member` before its local admin compatibility layer evaluates access. ## Data Ownership Topolo Pay owns order, transaction, refund, and payment-operation records. Nexus owns centralized external-service credential usage for supported outbound provider calls. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/transactions`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `transactions:read`, `customers:read`, `merchants:read`. - `/transactions` uses `/api/admin/transactions` with the `record.list` template and `pay.transactions.list` data source. - `/transactions/:id` uses `/api/admin/transaction/:id` with the `record.detail` template and `pay.transactions.detail` data source. - `/customers` uses `/api/admin/customers` with the `record.list` template and `pay.customers.list` data source. - `/merchants` uses `/api/merchants` with the `record.list` template and `pay.merchants.list` data source. - `/merchants/:id` uses `/api/admin/merchants/:id` with the `record.detail` template and `pay.merchants.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Pay deploys as a Cloudflare worker with admin and webhook surfaces. Standardized outbound payment routes require `NEXUS_SERVICE_TOKEN` and `NEXUS_ORGANIZATION_ID`; local webhook verification still uses `STRIPE_WEBHOOK_SECRET`. The isolated staging worker is published in the separate Topolo Staging Cloudflare account at `https://pay.stg.topolo.us`. Its staging build injects staging Auth and Pay origins, and the worker requires explicit Auth, Nexus, and Pay app URL bindings instead of falling back to production hosts. Pay stamps platform security headers, including HSTS, content-type sniffing protection, referrer policy, frame protection, cross-origin opener policy, and a restrictive permissions policy, on worker responses in both staging and production. ## Failure Modes - order, refund, status, or cancellation routes drift from the current Nexus payment standard - webhook verification and outbound payment calls are confused as the same integration boundary - worker responses lose the shared platform security-header baseline ## Debugging Start with `/systems/topolo-pay` and distinguish inbound webhook verification from outbound payment API calls before debugging provider issues. ## Use It Open [Topolo Pay](https://pay.topolo.app) for the human product surface. The [system handbook](/systems/topolo-pay) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-pay --json topolo actions --service topolo-pay --json topolo actions capabilities --service topolo-pay --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-pay) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Pay and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 5 published route(s) against `apps/TopoloPay` `origin/staging` `a8540c0d8627` on 2026-07-27. - Reconciled this page against `apps/TopoloPay` `origin/staging` `efcd323ba3d9` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloPay commits through a8c2813; reviewed 174 commits since 2026-06-03, including a8c2813 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); b7e1c68 Adopt canonical Topolo typography; f2fd1fa Split Pay startup bundle; 7734bdd Remove Pay Topolo vendor monolith. - Added Pay worker security headers on 2026-05-14 and verified the staging pentest header failure no longer applies. - Verified Pay app identity centralization on 2026-05-13 so the worker and admin shell resolve the environment app id from Auth by slug and the rebuilt admin bundle carries no hardcoded app ids. - Recorded the isolated Topolo Staging Pay worker target on 2026-04-29. - Verified Pay staging URL isolation on 2026-04-30 so the staging admin bundle and worker runtime resolve Auth, Pay, and Nexus through staging configuration. - Removed Pay's residual Worker `JWT_SECRET` handoff on 2026-04-18 so protected admin bearer-token authorization validates through Auth instead of local JWT claims. - Corrected Pay role normalization on 2026-04-24 so missing Auth role claims resolve to `member` before the admin compatibility layer runs. - Delegated Pay admin login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18. - Removed the remaining legacy Pay auth compatibility surface on 2026-04-11 so the live worker now resolves admin auth only through Topolo Auth naming and the shared middleware path - Promoted Pay admin browser SSO callbacks to Auth `/sso/exchange` on 2026-04-17 so callback URLs carry a one-time `sso_code` instead of bearer tokens - Restored the live Pay admin shell fallback for `/dashboard` on 2026-04-07 so direct app links and suite handoff keep loading the React admin frontend instead of the worker JSON 404 - Replaced the Pay admin launcher with the shared Topolo app switcher on 2026-04-07 so the live operator UI now uses the current suite icon set and standard cross-app launcher behavior instead of the older local overlay - Verified the Nexus-backed Topolo Pay outbound payment boundary on 2026-03-30 ## Topolo People Canonical URL: https://docs.topolo.app/applications/people Public overview of Topolo People in the Topolo application suite. ## What It Is Topolo People is part of the Topolo business application suite. It manages org-scoped employee records, configurable onboarding workflows, HR task tracking, and employee document generation in TopoloCompose from People context. ## Architecture The application uses the shared Topolo shell, Topolo Auth, and a People-owned D1 employee and onboarding record store. Employee document actions open TopoloCompose with the document type, style, audience, prompt, and selected employee source material already prepared. Onboarding templates define required fields, required documents, task templates, and signature requirements. People creates TopoloSign envelopes for signature requirements when an onboarding session starts and tracks the Sign envelope id on each related onboarding task. New hires enter through a dedicated onboarding landing and scoped shell, while organization users retain the People operations landing and workspace shell. Both surfaces use the shared Topolo authentication and landing contracts. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The scaffold baseline is live at `https://people.topolo.app`. ## API Reference Authenticated People APIs expose dashboard, employee record, onboarding template, onboarding session, and onboarding task routes under `/api/*` and validate requests through Topolo Auth. Employee document generation uses a People-to-Compose browser intent rather than a People-owned backend document API. ## Auth and Permissions Signed browser and API requests use Topolo Auth through app id `app_VDMBAonA5fKb`, supplied to the Worker as `APP_ID` rather than resolved through a runtime Auth slug lookup. ## Data Ownership Topolo People owns employee and onboarding records in D1 and scopes every row by authenticated organization. Compose receives selected employee fields as source material for generation. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/employees`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/employees` uses `/api/employees` with the `record.list` template and `people.employees.list` data source. - `/employees/:id` uses `/api/employees/:id` with the `record.detail` template and `people.employees.detail` data source. - `/onboarding` uses `/api/onboarding/sessions` with the `record.list` template and `people.onboarding.sessions.list` data source. - `/onboarding/:id` uses `/api/onboarding/sessions/:id` with the `record.detail` template and `people.onboarding.sessions.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments The scaffold baseline is live at `https://people.topolo.app`. ## Failure Modes - service registration and app routing can drift while the product is still planned - Compose URL intent fields can drift from the TopoloCompose browser contract - D1 migrations must be applied before deploying Worker code that depends on new employee tables - employee APIs must preserve the authenticated organization boundary - signature tasks can be blocked when the employee has no work email or the current user cannot create envelopes in TopoloSign ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo People](https://people.topolo.app) for the human product surface. The [system handbook](/systems/topolo-people) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-people --json topolo actions --service topolo-people --json topolo actions capabilities --service topolo-people --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-people) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo People and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the dedicated new-hire onboarding landing and scoped-shell entry policy against `apps/TopoloPeople` `origin/staging` `f16ae19e9825` on 2026-07-29. - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloPeople` `origin/staging` `cb4dc5312ad9` on 2026-07-27. - Reconciled this page against `apps/TopoloPeople` `origin/staging` `78d2d4b84200` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloPeople commits through f2c9a55; reviewed 361 commits since 2026-05-14, including f2c9a55 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 6b8db4a Stop blocking startup on i18n readiness; 3659a3e Adopt canonical Topolo typography; b2909bd Lazy load People shell. - Added configurable onboarding templates, onboarding sessions, onboarding tasks, and employee document placeholders on 2026-04-27. - Added D1-backed employee records and dashboard APIs on 2026-04-27. - Added one-click employee document launch into TopoloCompose on 2026-04-27. - Deployed Worker/static-assets baseline to `https://people.topolo.app` on 2026-04-23. - Scaffold generated on 2026-04-23 from `topolo apps scaffold`. ## Topolo Quro Canonical URL: https://docs.topolo.app/applications/quro Public overview of the QR creation, redirect, analytics, and authenticated UI surface in the Topolo portfolio. ## What It Is Topolo Quro is the QR creation, redirect, and scan-tracking application in the Topolo portfolio. ## Architecture The current repo shape includes an API worker, a redirect worker, a canonical modern UI, and a retained legacy UI used only for reference and parity checks. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces Use `/systems/topolo-quro` for the current deployment inventory and service metadata. ## API Reference The active contract centers on QR creation, templates, analytics, redirect resolution, and org-scoped authenticated browser flows. ## Auth and Permissions The canonical current UI uses the first-party Topolo auth pattern with authenticated routes, branded embedded password login on `quro.topolo.app`, and callback flows. The legacy UI should not be treated as the active auth model. Protected Quro API bearer-token requests validate through Auth and do not accept locally decoded JWT claims from a Worker secret. Browser SSO callbacks delegate one-time `sso_code` redemption to the shared `@topolo-io/auth-client` package, so callback URLs carry short-lived codes rather than bearer tokens or `/sso?token=` bridge payloads. The canonical browser UI keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal reload should reopen the authenticated dashboard rather than appearing signed out. Quro now also normalizes any missing Auth role claim to `member` in both the canonical browser UI and API worker bootstrap. ## Data Ownership Quro owns QR assets, redirect mappings, analytics, and related org-scoped settings and dashboards. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `codes:read`, `codes:write`, `series:read`, `analytics:read`. - `/dashboard` uses `/qurocodes` with the `record.list` template and `quro.codes.list` data source. - `/codes/:slug` uses `/qurocodes/:slug` with the `record.detail` template and `quro.codes.detail` data source. - `/series` uses `/series` with the `record.list` template and `quro.series.list` data source. - `/series/:id/dashboard` uses `/series/:id/dashboard` with the `record.detail` template and `quro.series.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Deploy Quro as a cluster of API, redirect, and authenticated UI surfaces. Treat the legacy UI as reference-only. ## Failure Modes - legacy UI behavior is mistaken for the live product contract - redirect and analytics behavior drifts from the authenticated create/manage surface - auth flows are documented from the wrong UI generation ## Debugging Start with `/systems/topolo-quro`, then confirm whether the failing behavior belongs to the canonical UI, redirect worker, or API worker. ## Use It Open [Topolo Quro](https://quro.topolo.app) for the human product surface. The [system handbook](/systems/topolo-quro) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-quro --json topolo actions --service topolo-quro --json topolo actions capabilities --service topolo-quro --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-quro) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Quro and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloQuro` `origin/staging` `e2624ecc21c7` on 2026-07-27. - Reconciled this page against `apps/TopoloQuro` `origin/staging` `7d86ee338645` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloQuro commits through 77b27b1; reviewed 360 commits since 2026-05-14, including 77b27b1 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); df339d0 Adopt canonical Topolo typography; d24b3eb Lazy load Quro startup surfaces; 8dc6375 Roll out ui-kit capture startup split. - Enabled same-tab browser session restore by default on 2026-04-23 so Quro reloads remain signed in after successful Auth handoff or refresh. - Corrected Quro role normalization on 2026-04-24 so missing Auth role claims resolve to `member` in both the canonical UI and API worker bootstrap. - Verified the canonical Quro branded password-login completion path on 2026-04-21 so first-party sign-in remains on the app origin after shared Auth persists the session. - Removed the Quro API worker's residual local `JWT_SECRET` handoff on 2026-04-18 so protected bearer-token requests validate through Auth. - Removed the canonical Quro `/sso?token=` browser bridge on 2026-04-18 so `/auth/callback` now relies on the shared Topolo browser auth client for code redemption - Added canonical Topolo Quro coverage and retired repo-local Quro docs on 2026-03-30 - Promoted canonical Quro browser SSO callbacks to Auth `/sso/exchange` on 2026-04-17 so callback URLs require a one-time `sso_code` instead of bearer tokens ## Topolo Roadmapper Canonical URL: https://docs.topolo.app/applications/roadmapper Public overview of Roadmapper, including AI-assisted project onboarding, durable planning sessions, and stakeholder presentation delivery. ## What It Is Topolo Roadmapper is the project and roadmap planning application in the Topolo portfolio. It organizes work as projects, roadmaps, and nested roadmap items. ## Architecture Roadmapper combines a web application for project planning with a worker-backed API that owns project, roadmap, and roadmap-item persistence. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces - Roadmapper web application - Roadmapper API worker - Topolo Auth for identity and tenant scoping ## AI Onboarding Roadmapper now supports an AI-first project creation path on `/projects/new`. - Users can keep multiple AI roadmap chats in progress before any project is created. - Each chat keeps its own conversation transcript, editable roadmap draft, and stage until a team decides to finalize it. - Draft and ready chats can be deleted if the team wants to discard a creation attempt before it becomes a project, and the app offers a short in-app undo window before the delete is finalized. - The AI creation screen is chat-first: the conversation fills the main workspace and the hierarchy preview or editor lives on a separate draft tab instead of a pinned side panel. - The generated draft is directly editable before approval so teams can refine names, dates, status, ownership, and nested structure without leaving the flow. - Finalizing one chat creates the project, its roadmaps, and the nested roadmap items in one step. ## Planning Sessions Roadmapper now exposes persisted planning-session endpoints for existing projects. Those sessions are now surfaced directly on each project page as scoped project chats. Teams can open one thread for the full project, one roadmap, or one roadmap-item branch, keep changes isolated inside that scope, and only apply them after confirmation. ## API Surface The AI onboarding flow now includes persisted chat-session endpoints plus the legacy direct draft endpoints: - `GET /projects/ai/status` returns whether AI onboarding is enabled in the current environment. - `GET /projects/ai/sessions` lists saved pre-project AI roadmap chats. - `POST /projects/ai/sessions` creates a new AI roadmap chat. - `GET /projects/ai/sessions/:id` loads one saved AI roadmap chat. - `PATCH /projects/ai/sessions/:id` persists direct edits to the current draft. - `DELETE /projects/ai/sessions/:id` removes one draft or ready AI roadmap chat. - `POST /projects/ai/sessions/:id/turns` continues one AI roadmap chat, updates its draft, and tolerates common provider field aliases or fenced JSON wrappers before surfacing a generation failure. - `POST /projects/ai/sessions/:id/apply` finalizes one AI roadmap chat into a real project. - `POST /projects/ai/draft` accepts conversation turns plus the current draft and returns `{ assistantMessage, draft }`. - `POST /projects/ai/apply` accepts the approved draft and creates the full hierarchy. Roadmapper also adds planning-session and presentation endpoints: - `GET /projects/:id/planning/sessions` - `POST /projects/:id/planning/sessions` - `GET /planning/sessions/:id` - `DELETE /planning/sessions/:id` - `POST /planning/sessions/:id/turns` - `GET /planning/sessions/:id/revisions` - `POST /planning/sessions/:id/scenarios` - `POST /planning/sessions/:id/apply` - `POST /projects/:id/presentations/generate` - `POST /roadmaps/:id/presentations/generate` - `POST /items/:id/presentations/generate` - `GET /presentations/:id` - `PATCH /presentations/:id` - `POST /presentations/:id/export` Manual project creation through `POST /projects` remains available and now persists the submitted project status. Planning sessions now carry explicit scope metadata: - `project` sessions can revise and apply the full hierarchy - `roadmap` sessions can update only the selected roadmap or the roadmap plus its descendants - `item` sessions can update only the selected item or that item plus its descendants When a roadmap-scoped or item-scoped chat is applied, siblings outside the selected scope are preserved. ## API Reference Roadmapper currently uses curated application documentation plus the system registry entry for route and deployment coverage. The AI onboarding routes live under the `/projects` API surface. ## Structured Draft Contract The AI draft uses one shared structure across generation, preview, and apply: - `project` with `name` and optional `description` - `roadmaps[]` with `name`, optional description and dates, plus nested `items` - `items[]` with optional status, priority, dates, assignee, and recursive `children` The apply path rejects drafts with invalid date ordering, duplicate roadmap names, more than 10 roadmaps, or more than 250 total items. ## Auth and Permissions Roadmapper relies on Topolo Auth for identity and org scoping. AI onboarding endpoints are protected and operate within the caller's tenant context. Roadmapper browser login handoff and one-time `sso_code` callback redemption delegate to the shared `@topolo-io/auth-client` package. Direct bearer-token callback URLs and `/sso?token=` bridge routes are not supported. The browser keeps a same-tab Auth token restore by default after sign-in and refresh, so a normal reload should return to the Roadmapper workspace rather than appearing signed out while cookie refresh catches up. Roadmapper now also normalizes any missing Auth role claim to `member`, and its vendored middleware limits platform-wide bypass to `platform_super_admin` and `platform_admin` users in the Auth `admin` org. Roadmapper API authorization fails closed when Auth validation is unavailable; local JWT claim fallback is not part of the supported production contract. The API worker now requires Topolo Auth validation without a Roadmapper-local JWT secret handoff or vendored local HS256 verifier. Roadmapper resolves its concrete Auth app id from the `topolo-roadmapper` service slug at runtime. The browser receives that identity from the Roadmapper API `/api/app-identity` endpoint before booting shared auth, shell, API, and API-key flows. ## Data Ownership Roadmapper owns persisted pre-project AI roadmap chats, project records, roadmap records, and roadmap-item records, including the hierarchy created when an approved AI draft is applied. It now also owns planning sessions, revisions, scenarios, and presentation decks generated from project state. ## Presentation Delivery Roadmapper can now generate stakeholder-ready presentations from live planning state. Each deck is available as a responsive web presentation and can also be exported to PPTX from the same slide specification. Decks include summary copy, metrics, roadmap timeline content, risks, and next actions and remain editable after generation. Presentation generation is available from: - the full project - an individual roadmap - a roadmap-item branch and its descendants ## Guest Sharing Roadmapper now supports project, roadmap, and roadmap-item guest links. Links can be time-limited or non-expiring and now support two access modes: - `view` for read-only review - `edit` for authenticated guest item edits inside the shared scope Editable guest links require sign-in so Roadmapper can attribute every item change to a guest identity for logging and audit. Project and roadmap guest links can optionally allow branch drill-down into child roadmap items. Item guest links always open a dedicated shared branch surface rooted at the selected roadmap item and its descendants. Invite delivery now uses the Roadmapper API instead of `mailto:` links. Email invites are sent server-side through Nexus using the Resend provider, and WhatsApp invite composition remains available when the deployment is configured for it. Project guest links open a dedicated project guest surface where viewers can step from the full project into a roadmap and then into a child branch when navigation permission is enabled. Roadmap and roadmap-item guest views now expose full item titles and descriptions in-page through a guest inspector instead of relying on truncation. ## Feature Enablement AI draft generation now routes through Nexus instead of calling OpenAI directly from the Roadmapper worker. The AI path is considered enabled when the Roadmapper API can reach Nexus and the current request has auth context that Nexus can verify. If Nexus is unavailable for the current environment, the web app falls back to the manual project creation path. The Roadmapper API now treats `https://nexus.topolo.app` as the Nexus dashboard origin and `https://nexus-api.topolo.app` as the default Nexus gateway origin when no explicit `NEXUS_GATEWAY_URL` override is configured. Plain-text or HTML upstream failures still surface as provider errors instead of a JSON parse exception in the browser. ## Mobile Experience The checked-in mobile experience contract is **published** in `native_capability` mode. Its fallback route is `/projects`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `projects:read`, `projects:write`, `roadmaps:read`, `roadmaps:write`. - `/projects` uses `/api/projects` with the `record.list` template and `roadmapper.projects.list` data source. - `/projects/:id` uses `/api/projects/:id` with the `record.detail` template and `roadmapper.projects.detail` data source. - `/roadmaps` uses `/api/roadmaps` with the `record.list` template and `roadmapper.roadmaps.list` data source. - `/roadmaps/:id` uses `/api/roadmaps/:id` with the `record.detail` template and `roadmapper.roadmaps.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Roadmapper deploys as a web app plus API worker surface. AI draft generation and notification email delivery now depend on Nexus gateway connectivity instead of app-local provider keys. The web app now waits for an explicit refresh before a new service worker takes control so deploys do not strand users between old and new hashed asset bundles. The production web build must not embed a concrete app id. If the browser bundle carries a stale concrete app id, standard tenant users can be sent back to `/login` even while super-admin accounts continue to work. The browser auth client also lets cookie-backed Auth refresh calls finish instead of client-aborting them mid-flight. Auth rotates the refresh cookie on success, so aborting that request can leave the next page reload with a stale refresh token. ## Failure Modes - missing or unreachable Nexus connectivity leaves AI onboarding disabled or unavailable - interrupted browser Auth refresh calls can invalidate the current refresh cookie for the next reload - saved AI roadmap chats can remain in progress across multiple draft stages before one is finalized - invalid model output causes a server-side repair retry and then a typed failure - apply validation blocks malformed or oversized drafts before any writes - if apply fails after project creation starts, the worker deletes the new project so partially created roadmaps and items are not left behind - planning-session apply can fail if the generated document has no roadmaps or items - presentation export depends on the generated deck and the browser-side PPTX export path being available ## Debugging - confirm `GET /projects/ai/status` returns `enabled: true` - verify the Roadmapper API can reach `https://nexus-api.topolo.app` or the configured `NEXUS_GATEWAY_URL` with the caller's auth context - verify the Roadmapper web app and API are pointed at the same environment - verify `GET /api/app-identity` resolves the `topolo-roadmapper` slug to the active Auth app id and the browser bundle does not embed a concrete app id - if sign-in appears to succeed and then returns to `/login`, inspect the `/auth/callback` handoff before treating the issue as a missing tenant entitlement - if AI generation fails with an OpenAI `response_format` schema error, verify the Roadmapper structured-output schema is using required nullable fields for values that are optional in the stored draft model - if AI generation fails after the provider returns JSON, inspect whether the model emitted a tree-shaped draft instead of the canonical project and roadmaps structure - inspect the approved draft payload if apply validation rejects the hierarchy ## Use It Open [Topolo Roadmapper](https://roadmapper.topolo.app) for the human product surface. The [system handbook](/systems/topolo-roadmapper) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-roadmapper --json topolo actions --service topolo-roadmapper --json topolo actions capabilities --service topolo-roadmapper --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-roadmapper) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Roadmapper and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloRoadmapper` `origin/staging` `5dc616c1660b` on 2026-07-27. - Reconciled this page against `apps/TopoloRoadmapper` `origin/staging` `dff708dba835` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloRoadmapper commits through f728884; reviewed 398 commits since 2026-05-14, including f728884 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); c0c9243 Split Roadmapper startup shell bundle; 84ce6ab Adopt canonical Topolo typography; 5d24a50 Roll out ui-kit capture startup split. - Removed concrete Roadmapper app ids from browser, API, Worker vars, Notify, API-key, widget, and seed validation paths on 2026-05-13. Roadmapper now centralizes app identity in app-identity modules and resolves concrete app ids from Auth slugs at runtime. - Enabled same-tab browser session restore by default on 2026-04-23 so Roadmapper reloads remain signed in after successful Auth handoff or refresh. - Corrected Roadmapper role normalization on 2026-04-24 so missing Auth role claims resolve to `member`, while platform-wide bypass in the vendored middleware now follows the canonical `platform_*` roles in the Auth `admin` org. - Removed the Roadmapper `/sso?token=` browser bridge and app-local login URL construction on 2026-04-18 so login handoff and `/auth/callback` code redemption now rely on the shared Topolo browser auth client - Hardened Roadmapper API authorization on 2026-04-18 so protected routes require Auth validation and no longer trust local JWT claims as an outage fallback; commit `2f8a834` deployed worker version `a9282e78-e572-48c0-81d5-1bfda6134e95` - Removed the remaining Roadmapper API local JWT secret handoff on 2026-04-18 - Corrected the Roadmapper production web app identity on 2026-04-12 so standard tenant users are no longer evaluated against a stale browser Auth catalog entry during `/refresh` and API requests - Corrected the Roadmapper browser callback flow on 2026-04-12 so login completion no longer depends on an immediate Auth `/refresh`, avoiding callback-to-login loops when the refresh cookie is not yet usable - Corrected the Roadmapper Nexus fallback host on 2026-04-12 so AI turns now default to the Nexus gateway worker rather than the Nexus dashboard origin, and upstream edge failures still surface as typed provider errors instead of JSON parse errors in the browser - Moved Roadmapper AI onboarding to the working Nexus xAI model on 2026-04-12 after the configured OpenAI path began failing production requests with `unsupported_country_region_territory` - Corrected the Roadmapper structured-output schema on 2026-04-12 so AI onboarding turns use required nullable fields where the stored draft model treats values as optional - Hardened Roadmapper AI-response normalization on 2026-04-12 so tree-shaped provider output is coerced into the stored draft hierarchy before final validation - Surfaced scoped project chats on 2026-04-12 so each project page now exposes persistent project, roadmap, and item planning threads with scope-preserving apply behavior - Added deletion for non-finalized AI onboarding chats on 2026-04-12 so discarded pre-project conversations can be removed from the creation surface - Tightened the Roadmapper web update path on 2026-04-12 so service-worker updates no longer switch clients immediately during hashed-asset deploys - Added persisted multi-chat AI onboarding on 2026-04-12 so teams can keep multiple roadmap chats in progress and finalize only the selected one into a real project - Expanded guest sharing on 2026-04-08 with item-level links, `view` or `edit` access modes, authenticated guest edits with audit logging, server-side Resend invites, and guest item inspector surfaces for full title and description visibility - Tightened the Roadmapper in-app command palette shortcut on 2026-04-08 so `Cmd/Ctrl+K` no longer intercepts the shared `Cmd/Ctrl+Shift+K` app-switcher shortcut - Added project guest sharing and scoped project, roadmap, or branch presentation generation on 2026-04-07 - Refreshed the main project, roadmap, item, share, and presentation surfaces on 2026-04-07 to replace the heavy flat card treatment with lighter gradient panels - Expanded roadmap guest sharing on 2026-04-07 with non-expiring links, optional child-branch navigation, and invite actions in the share modal - Stabilized dependency-overlay registration on 2026-04-07 so timeline/detail views no longer hit a React nested-update loop while rendering dependency bars - Verified editable AI draft review, persisted planning sessions, shared timeline rendering, and responsive presentation/PPTX delivery on 2026-04-07 - Verified against the current AI onboarding, apply semantics, and project-create flow on 2026-03-29 ## Topolo Sign Canonical URL: https://docs.topolo.app/applications/sign Public overview of Topolo Sign in the Topolo application suite. ## What It Is Topolo Sign is part of the Topolo business application suite. It manages electronic-signature templates, envelopes, recipient signing links, and signature audit records for generated or uploaded documents. ## Architecture The application uses the shared Topolo shell and Topolo Auth for authenticated workspace users. Recipient signing sessions use token-scoped public links so external signers do not need a Topolo account. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The workspace is live at `https://sign.topolo.app`. Recipient signing links are served at `/sign/:token`. ## API Reference Authenticated workspace routes manage templates and envelopes under `/api/templates` and `/api/envelopes`. Token-scoped recipient routes are available under `/api/signing/:token`. ## Auth and Permissions Signed browser and API requests use Topolo Auth through app id `app_Bd8pRw5ZqRBT`, supplied to the Worker as `APP_ID` rather than resolved through a runtime Auth slug lookup. Recipient links are scoped by signing token rather than platform login. ## Data Ownership Topolo Sign owns organization-scoped signature templates, envelopes, recipients, and audit events in its production D1 store. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/envelopes`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`. - `/envelopes` uses `/api/envelopes` with the `record.list` template and `sign.envelopes.list` data source. - `/envelopes/:id` uses `/api/envelopes/:id` with the `record.detail` template and `sign.envelopes.detail` data source. - `/templates` uses `/api/templates` with the `record.list` template and `sign.templates.list` data source. - `/templates/:id` uses `/api/templates/:id` with the `record.detail` template and `sign.templates.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Production is live at `https://sign.topolo.app`. ## Failure Modes - source applications should not mark a document signed until the Sign envelope and recipient statuses confirm completion - signed-PDF/certificate artifact generation is not yet part of the first Sign implementation ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Sign](https://sign.topolo.app) for the human product surface. The [system handbook](/systems/topolo-sign) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-sign --json topolo actions --service topolo-sign --json topolo actions capabilities --service topolo-sign --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-sign) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Sign and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloSign` `origin/staging` `238b280f702a` on 2026-07-27. - Reconciled this page against `apps/TopoloSign` `origin/staging` `5d7d0adb756b` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloSign commits through f66da1b; reviewed 311 commits since 2026-05-14, including f66da1b chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 59cf23d Stop blocking startup on i18n readiness; 5df6127 Adopt canonical Topolo typography; 63b818f Fix Sign web deploy build command. - Added durable signature envelopes, templates, recipient links, and audit records on 2026-04-27. - Deployed Worker/static-assets baseline to `https://sign.topolo.app` on 2026-04-23. - Scaffold generated on 2026-04-23 from `topolo apps scaffold`. ## Topolo Social Studio Canonical URL: https://docs.topolo.app/applications/social-studio Public overview of the hybrid desktop and Cloudflare runtime used for AI-assisted social content planning and generation. ## What It Is Topolo Social Studio is a hybrid desktop and web production surface for planning, generating, and managing social-first creative work. ## Architecture The system combines a marketing/web shell, an authenticated API worker, a queue worker for generation orchestration, and a macOS desktop shell. Auth manages identity and Nexus now owns the external AI provider invocation path. Studio requires the Topolo Brand service in every deployed API environment. Explicitly selected or workspace-mapped kits must resolve through Brand and store the exact immutable version used for planning and generation; an unavailable Brand service fails closed, while creating a project without selecting a kit remains an explicit product choice. Studio no longer owns a second mutable brand-kit table or mutation surface. Composition and export contracts support square, landscape, 4:5 portrait, and 9:16 portrait channel ratios. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The primary public surface is `https://studio.topolo.app`, backed by Cloudflare-hosted worker runtimes and a local desktop shell for creator workflows. ## API Reference Use `/systems/topolo-social-studio` for the current runtime and worker route inventory. Provider-facing AI operations are invoked through Nexus rather than documented as direct vendor contracts here. ## Auth and Permissions Studio relies on Topolo Auth for session verification and workspace access. Its web and desktop shells now use the shared Topolo browser auth client through a thin application wrapper, including login handoff, service-aware cookie refresh, single-pass callback-code redemption, and logout propagation. Workspace APIs now require the matching Social Studio service permission before workspace membership, owner, or export-policy rules can narrow access, and local workspace ownership is no longer inferred from broader Auth role names. The app owns the stable `topolo-social-studio` Auth slug and resolves the concrete app id at runtime, including the browser shell identity used by login and shared app chrome. Protected bootstrap preserves the raw Auth role separately, resolves the caller's Studio workspace membership when workspace state is available, and returns the local `owner/member` role from that membership in the shell payload. Improve Topolo stays inside the authenticated account menu rather than a standalone floating control. AI-assisted routes preserve org and user attribution when they invoke Nexus-backed provider workflows. ## Data Ownership Topolo Auth owns workspace identity and accessible-workspace listing. Studio owns workspace-scoped projects, briefs, creative plans, scenes, assets, membership policy, and generation state. Nexus owns the provider keys and platform-level usage attribution for supported AI vendors. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/app/projects`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`, `social-studio:projects:read`, `social-studio:projects:write`. - `/app/projects` uses `/api/workspaces/:workspaceSlug/projects` with the `record.list` template and `studio.projects.list` data source. - `/app/projects/:projectId/brief` uses `/api/workspaces/:workspaceSlug/projects/:projectId/planning` with the `record.detail` template and `studio.projects.detail` data source. - `/app/projects/:projectId/review` uses `/api/workspaces/:workspaceSlug/projects/:projectId/sync` with the `activity.timeline` template and `studio.projects.review` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Studio deploys as a hybrid surface with separate marketing/web, API worker, queue worker, and desktop packaging flows. The Topolo-owned staging mirror runs the web surface at `studio.stg.topolo.us` and the API worker at `studio-api.stg.topolo.us`. ## Failure Modes - auth context missing for protected workspace routes - queue worker unavailable for generation processing - Nexus connectivity or provider configuration missing for AI-assisted planning or generation - Brand service binding or service identity missing, or a selected canonical kit no longer resolving ## Debugging Start with `/systems/topolo-social-studio` for deployment and runtime detail. If AI planning or generation fails, verify the app can reach Nexus and that the expected org/user context is being forwarded. ## Use It Open [Social Studio](https://studio.topolo.app) for the human product surface. The [system handbook](/systems/topolo-social-studio) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-social-studio --json topolo actions --service topolo-social-studio --json topolo actions capabilities --service topolo-social-studio --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-social-studio) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Social Studio and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified staging denial behavior on 2026-07-31 against `apps/TopoloSocialStudio` `2536a6d3567f`: protected bootstrap now returns the explicit not-found contract when no Studio workspace grant exists instead of failing with an internal error. - Verified the native_capability mobile experience contract and its 3 published route(s) against `apps/TopoloSocialStudio` `origin/staging` `a76f99cb0794` on 2026-07-27. - Reconciled workspace verification on 2026-06-28 against apps/TopoloSocialStudio commits through ed29d3d; reviewed 324 commits since 2026-05-14, including ed29d3d chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); a4b7129 Split Social Studio authenticated shell bundle; 62c45e3 Adopt canonical Topolo typography; d8cb398 Roll out ui-kit capture startup split. - Moved Social Studio app identity to runtime slug resolution on 2026-05-13 so public web, desktop, and API surfaces no longer ship concrete app identifiers. - Removed Social Studio's standalone floating Improve Topolo controls on 2026-05-12 so the web and desktop shells keep the report workflow in the authenticated account menu. - Verified the isolated Topolo Staging deployment on 2026-04-30; `studio.stg.topolo.us` and `studio-api.stg.topolo.us/health` returned HTTP 200. - Corrected the Social Studio callback effect on 2026-04-20 so successful Auth handoff no longer stalls on the callback screen after exchanging the one-time code. - Corrected Social Studio bootstrap role scoping on 2026-04-24 so the API worker now resolves workspace membership for the authenticated org workspace, returns the local `owner/member` role in bootstrap, and still preserves the raw Auth role separately. - Delegated Social Studio login handoff and callback-code redemption to the shared Topolo Auth client on 2026-04-18. - Stopped rewriting Social Studio workspace ownership from cross-app Auth role names on 2026-04-11 so the public worker contract now preserves Auth role diversity while keeping workspace owner rules local to Studio - Standardized Social Studio workspace-route permission enforcement on 2026-04-10 so protected APIs no longer rely on workspace membership or owner checks alone - Reconfirmed on 2026-04-07 that Social Studio is the sole live Studio-branded application at `studio.topolo.app` - Standardized Social Studio browser auth on the shared Topolo auth client on 2026-03-31 - Standardized the public product label to `Social Studio` across the web and desktop authenticated shells and recorded the production marketing-web Worker target in CloudControl on 2026-04-04 - Added canonical system coverage and documented the Nexus-backed AI integration path on 2026-03-29 ## Socialize Canonical URL: https://docs.topolo.app/applications/socialize Public overview of the social publishing platform, brand-scoped resource bindings, and content operations. ## What It Is Socialize is the social publishing and campaign platform for posts, media, analytics, integrations, and brand-scoped publishing workflows. Its integrations surface returns Facebook Pages and eligible Facebook Groups together, preserves the exact Facebook target, LinkedIn organization, or Instagram account chosen for a post during later edits, and combines live Nexus account state with Socialize-owned brand target selections and publishing health. ## Architecture Socialize combines the application surface with a worker/API runtime that exposes brand-scoped content operations and analytics. Its AI-assisted text generation, image generation, trend workflows, invitation email delivery, and connected-provider credential handling route through Topolo Nexus while Socialize keeps ownership of prompt construction, domain validation, publishing intent, and content persistence. Nexus owns connected-account identity, avatar/profile data, lifecycle, scopes, expiry, and encrypted tokens; Socialize stores only the stable Nexus reference plus brand-specific target selections and runtime health. Billing and referrals are platform-level surfaces outside the Socialize workspace and API. Socialize requires Topolo Brand in every deployed environment and resolves a published Brand version for the active Socialize brand before text or programmatic-media generation. Readiness and generation fail closed when the Brand binding, service identity, or canonical snapshot is unavailable; there is no unbranded compatibility path. The generator uses only approved channel-compatible claims and CTAs, embeds the canonical primary logo, derives readable artwork colours from the published palette, and records the exact kit and version used. Manual brand colour, font, and name overrides are no longer accepted by these generation routes. The browser workspace keeps the Improve Topolo contribution entrypoint inside the shared account menu rather than rendering a floating report button over product workflows. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces See `/systems/socialize` for the current runtime host and deployment surfaces. ## API Reference Use `/reference/apps/socialize` and the generated OpenAPI detail for routes, operations, and request examples. Topolo CLI and MCP clients can discover and run Socialize actions for brands available to their credential. The action catalog includes typed post creation, campaign creation and scheduling, publishing-readiness checks, and follow-up reads for verification. Roles and brand-bound API keys remain constrained by the same platform and Socialize permissions as the browser. ## Trend And Queue APIs Socialize now exposes a trend-native handoff for connected automation and mobile review flows: - `/api/trends` returns normalized trend or shared-seed items for a brand - `/api/content-strategy/suggestions/generate-from-trends` creates platform-specific draft suggestions directly from those items - `/api/seeds/share` stores time-sensitive shared seeds and routes them to one, selected, or all brands - `/api/content-ops/deck` returns a freshness-ranked approval deck for mobile review - `/api/brands/:brandId/publishing-readiness` reports token-aware scheduling readiness for X, LinkedIn, Facebook, Instagram, Threads, TikTok, and YouTube Trend-backed suggestions include source attribution, freshness, and dedupe metadata so downstream schedulers can act on them safely. The mobile app also accepts native share-sheet intake. A link or post shared into Socialize from another app is converted into a reusable seed, then routed from a single brand list with a quick-select-all action before suggestion generation starts. Socialize infers `one`, `selected`, or `all` targeting from that choice. The iPhone app also falls back to the shared App Group payload store on launch and resume so cold-start shares still land in the brand-targeting flow. The same mobile approval deck now supports `Tinder` mode for swipe review with a shared media-and-copy scroll flow, `Story` mode for an Instagram-story-style review surface with full-width left or right tap navigation, a dedicated media panel, one shared vertical scroll flow for media and copy, and the same edit sheet opened by double-tap or press-and-hold, and `Feed` mode for a scrollable queue with per-item actions, context controls, inline media controls, and expandable long-copy handling. Socialize stores that preference on-device so the app reopens in the operator's chosen review layout. Scheduled posts can be reverted to drafts from the browser posts list; the API clears the schedule and returns the updated draft state before the UI reports success. Campaign scheduling creates durable posts for each configured day/time and enabled platform, and retries do not duplicate those occurrences. Scheduled publishing uses the active connection for the target brand and platform. It prefers the post author's connection when available, then falls back to another active brand connection so approved brand content can publish even when the scheduler actor is not the user who connected the social account. X connections request read, write, media upload, and offline refresh scopes, and profile hydration uses the current X API host before the legacy `api.twitter.com` API host. Before publishing, the scheduler reloads the post row so current copy and rescheduled times win over older queued snapshots. Expired X tokens are refreshed through the API worker's Auth-verified internal service route, keeping provider OAuth client secrets on the API surface while scheduled publishing receives the fresh connection token. ## Auth and Permissions Socialize uses Auth-managed service slugs, API key scopes, and centralized brand resource binding catalogs. The browser, mobile app, and API worker resolve the `topolo-socialize` slug through Auth at runtime instead of shipping a concrete app ID in source or static assets. The API worker validates staff bearer tokens through centralized Auth validation and does not keep a local JWT-secret trust path. Browser brand selection and API-key brand binding checks now share the platform resource-context helper while Socialize continues to own brand records and brand membership roles. Its browser session flow now uses the shared Topolo cookie-refresh auth client rather than a Socialize-specific browser auth implementation. The Socialize CLI now uses the same shared Topolo auth client for direct credential login and token validation instead of its own Auth protocol implementation. Socialize also defaults any missing Auth role claim to `member` across its CLI and worker-side token intake paths. The browser sign-in callback requires Auth's one-time `sso_code` handoff on `/auth/callback` and delegates callback-code redemption to the shared Topolo Auth client before storing a local session; direct token callback URLs are not accepted. The embedded browser login keeps form controls interactive while background session bootstrap runs, and the browser app restores the short-lived access token from same-tab session storage after a normal refresh before falling back to cookie refresh. Auth `platform_super_admin` and `platform_admin` users operating from the `admin` tenant can administer brand invite, member-management, and integration-disconnect mutations even when they are not stored as local members of that brand, while org-scoped `super_admin` users still follow the normal brand membership manage checks and owner-only operations remain restricted. The mobile app now holds on the Socialize splash screen while a saved session is being restored instead of briefly flashing the login form first. `main()` preloads the mirrored local session snapshot before the router renders, and the app root stays on splash until auth bootstrap completes without bailing out on a fixed startup timeout. It waits briefly for iPhone protected data before reading secure storage, restores from locally persisted auth state before the background user refresh completes, and if secure storage comes back empty or throws it falls back to a mirrored local session snapshot before reconstructing a local user from access-token claims, so reopening the app does not depend on an immediate network round-trip to keep the user signed in. The login form now exposes iPhone autofill-friendly email and password fields, remembers the last successful email locally, and commits the autofill context on successful sign-in so iOS Passwords can help reuse credentials. If biometric unlock is enabled, Socialize now gates the restored session behind Face ID or Touch ID when the app returns from the background. User-driven AI and email Nexus-backed flows forward the caller's bearer token so usage stays attributed to the correct org and user context. Social-provider OAuth, token-refresh, callbacks, publishing, and account-management flows use Auth-minted service context with the brand's org attribution, delegated user ID where applicable, and the registered `app_topolo_socialize` Nexus app ID. Nexus is the sole source of connected-provider credentials and lifecycle state. Browser inventory is a hydrated view of that live Nexus state plus Socialize-owned brand selections and runtime metrics; local rows contain no provider token or provider profile copy. ## Data Ownership Socialize owns the actual brand and publishing resources while Auth owns the bindable-resource index consumed by TopoloOne. Brand owners can move an existing Socialize brand to another accessible Topolo Auth organization. The brand keeps its Socialize ID and content history while its org-scoped ownership moves to the target organization. The transfer flow uses a searchable target-organization picker and copyable target organization ID confirmation before the ownership move is submitted. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/posts`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `posts:read`, `posts:write`, `calendar:read`, `calendar:write`, `accounts:read`, `accounts:write`. - `/posts` uses `/api/posts` with the `record.list` template and `socialize.posts.list` data source. - `/posts/:id` uses `/api/posts/:id` with the `record.detail` template and `socialize.posts.detail` data source. - `/campaigns` uses `/api/campaigns` with the `record.list` template and `socialize.campaigns.list` data source. - `/campaigns/:id` uses `/api/campaigns/:id` with the `record.detail` template and `socialize.campaigns.detail` data source. - `/brands` uses `/api/brands` with the `record.list` template and `socialize.brands.list` data source. - `/brands/:id` uses `/api/brands/:id` with the `record.detail` template and `socialize.brands.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Socialize deploys with an application frontend plus worker/API surface documented in the generated system handbook. The Topolo-owned staging mirror runs the frontend at `socialize.stg.topolo.us` and the API worker at `socialize-api.stg.topolo.us`. Standardized AI flows no longer rely on app-local Google or xAI provider secrets in the worker runtime. User-driven routes forward bearer auth to Nexus, and background worker flows use the trusted service token plus brand org attribution. Trusted operator automation can generate post media through an internal Socialize image route, but the generated assets still pass through the same Nexus-backed image handlers and Socialize R2 media storage as browser-generated images. ## Failure Modes - missing `brands.read` scope for resource binding workflows - wrong API origin or CORS misconfiguration - Auth catalog drift for brand-scoped keys - Nexus connectivity or auth-context forwarding is missing for AI or email routes - worker code regresses to a direct vendor fallback instead of using Nexus ## Debugging Use `/systems/socialize` for runtime, bindings, and deployment detail, and `/reference/apps/socialize` for API operations and OpenAPI-backed routes. If AI or email flows stop working, verify the worker is calling Nexus rather than a vendor API directly and that Nexus has the required provider keys configured. ## Use It Open [Socialize](https://socialize.topolo.app) for the human product surface. The [system handbook](/systems/socialize) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query socialize --json topolo actions --service socialize --json topolo actions capabilities --service socialize --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=socialize) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Socialize and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Completed and staging-verified the Nexus-only connected-provider boundary on 2026-08-01 at Socialize source `0c7fecd2fd61131e5ceb305b76bccaae3271fa99`; the API and scheduler hydrate Nexus state, local storage is reference/selection/runtime-only, and provider callbacks and refreshes update Nexus first. - Verified the native_capability mobile experience contract and its 6 published route(s) against `apps/TopoloSocialize` `origin/staging` `b63b0f5f25bf` on 2026-07-27. - Adopted immutable Topolo Brand versions for generated copy and programmatic media on 2026-07-15, including approved claim and CTA enforcement, canonical logo embedding, readable colour selection, and claim-safe deterministic fallbacks. - Verified agent-operated post and campaign workflows on 2026-07-14, including canonical brand isolation, server-derived actors, seven-provider publishing readiness, typed action contracts, durable campaign cadence expansion, and follow-up verification actions. - Reconciled workspace verification on 2026-06-28 against apps/TopoloSocialize commits through 0028d6e; reviewed 116 commits since 2026-06-18, including 0028d6e chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 5c65539 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); ce0206f Defer Socialize bug reporter startup bundle; fdfe1c2 Split Socialize startup shell bundle. - Removed hard-coded Socialize Auth app IDs on 2026-05-13 so browser login, launcher, mobile auth bootstrap, API-key management, seed sync, notification events, and worker auth validation use slug-resolved app identity. - Adopted the shared resource-context package for brand request context and API-key binding parsing on 2026-06-16. - Removed the floating browser Improve Topolo button on 2026-05-12 so Socialize uses the shared account-menu contribution entrypoint while preserving the report modal and keyboard shortcut. - Fixed the production integrations route on 2026-05-06 so browser-driven Socialize integration inventory and account-management flows call Nexus with the Socialize worker service client plus delegated user/org attribution while preserving Socialize-owned local connection rows. - Removed the dummy Socialize admin page on 2026-05-06 so platform administration is no longer shown as a Socialize workspace surface. - Made Socialize integration inventory refresh visible on 2026-05-06 so connected accounts do not appear without an in-page status cue. - Reduced Socialize integrations loading latency on 2026-05-06 so browser inventory reads no longer wait on Nexus credential lookup or connection synchronization before rendering connect actions. - Verified scheduled publishing connection resolution on 2026-05-02 so approved brand posts can publish through the brand's active platform connection even when the post author differs from the connected account owner. - Removed reachable Socialize billing and referral routes on 2026-05-06 so billing, referrals, and subscription rewards remain platform-level surfaces instead of app-local Socialize API or workspace features. - Verified Socialize deploys against the shared CloudControl short-lived token wrapper on 2026-05-06; Socialize stays on the existing deploy Wrangler path until the Cloudflare Worker versions endpoint accepts the staging API worker binding set. - Updated the X OAuth connection flow on 2026-05-02 so image publishing requests media-upload permission and profile hydration tries the current X API host before the legacy `api.twitter.com` API host. - Verified scheduled queue rehydration on 2026-05-02 so edited scheduled posts publish with the current copy and schedule instead of stale queue-message snapshots. - Verified scheduled X token refresh on 2026-05-02 so the scheduler uses the API worker's internal refresh route rather than requiring X OAuth client secrets in the scheduler worker. - Verified internal Socialize image generation on 2026-05-02 so trusted operator automation can create post media through the same Nexus-backed image handlers and R2 storage used by browser image tools. - Aligned Socialize Nexus service-token calls with the registered `app_socialize` app ID on 2026-05-02. - Verified the isolated Topolo Staging deployment on 2026-04-30; `socialize.stg.topolo.us` and `socialize-api.stg.topolo.us/health` returned HTTP 200. - Verified the Socialize integration readiness contract on 2026-04-24 so LinkedIn Company now reads from dedicated production secrets, Instagram OAuth requests publish scopes that match Meta's current content-publishing docs, TikTok is explicitly marked sandbox-only while `TIKTOK_USE_SANDBOX` remains enabled in production, and planned providers are no longer treated as production-ready publish targets in the browser compose flow. - Corrected Socialize role normalization on 2026-04-24 so CLI and worker-side token intake resolve missing Auth role claims to `member`. - Verified Socialize publish-target persistence on 2026-04-24 so Facebook Group targets now reach the browser integrations flow, edited posts retain their explicit Facebook, LinkedIn, or Instagram destination, and scheduled Instagram publishing uses the saved account target. - Verified platform-admin brand invite and member administration on 2026-04-24 so only `platform_super_admin` and `platform_admin` sessions from Auth's `admin` tenant can revoke invites, disconnect integrations, and manage brand team state without a local member row, while owner-only operations remain restricted. - Verified brand transfer confirmation and invite revocation on 2026-04-23 so owners can search target organizations, copy the target organization ID, revoke pending invites reliably, and keep the non-member team-management bypass restricted to admin-tenant platform roles. - Verified brand organization ownership transfer on 2026-04-23 so an existing brand can move to another accessible Topolo Auth organization without changing its brand ID or content history. - Verified scheduled-post revert-to-draft handling on 2026-04-23 so the API response returns draft state before the browser reports success. - Verified browser login controls and same-tab refresh restore behavior on 2026-04-23 so the embedded sign-in form remains usable during background bootstrap and refresh no longer loses the short-lived app session before cookie refresh completes. - Delegated Socialize browser callback-code redemption to the shared Topolo Auth client on 2026-04-18 so the web helper no longer owns a direct `/sso/exchange` fetch. - Verified the Socialize browser Auth callback on 2026-04-17 so it accepts only one-time `sso_code` handoff values and no longer exposes direct-token callback routes - Updated the Socialize CLI `axios` dependency to the patched 1.14.0 line to pick up upstream denial-of-service fixes on 2026-04-02 - Verified persistent mobile session restore without the transient login flash and without requiring an immediate network user refresh, including preloading mirrored local session state in `main()`, a root-level splash gate, saved access-token claim restore, and a protected-data wait on iPhone when secure storage is not readable or throws immediately at launch, on 2026-04-02 - Verified iPhone autofill-aware login fields, last-used email hydration, and biometric quick-unlock gating for restored sessions on 2026-04-02 - Verified the simplified single-list brand targeting flow for native share-sheet intake on 2026-04-02 - Verified story-mode left/right navigation across the full mobile screen width plus a single shared media-and-copy scroll flow on 2026-04-02 - Verified staged mobile media uploads through the authenticated mobile API client on the protected Socialize host, plus shared media-and-copy scrolling in Tinder mode, on 2026-04-02 - Verified shared bottom-sheet editing for swipe/story review plus the dedicated story media panel and view-mode copy on 2026-04-02 - Verified persisted `Tinder`, `Story`, and `Feed` review modes for the mobile approval deck, with feed-mode context controls attached to each item plus inline media and `Read more` handling in feed cards, on 2026-04-02 - Verified the trend, share-seed, and publishing-readiness handoff surfaces on 2026-04-01 - Verified native Socialize share-sheet intake into the brand-targeted seed flow on 2026-04-01 - Verified iPhone cold-start share payload recovery from the shared App Group store on 2026-04-01 - Standardized Socialize browser auth on the shared Topolo auth client on 2026-03-31 - Standardized Socialize CLI auth on the shared Topolo auth client on 2026-03-31 - Verified against the current centralized brand resource-binding model on 2026-03-30 - Verified the Nexus-backed Socialize text, image, email, and billing call paths on 2026-03-30 ## TopoloSpaces Canonical URL: https://docs.topolo.app/applications/spaces Private Topolo business app for importing, viewing, and sharing organization-owned 3D spaces. ## What It Is TopoloSpaces gives a Topolo organization a private spatial asset library. Teams can import existing `.sog`, `.ply`, and `.zip` splat exports, track processing state, view ready SOG scenes, annotate spaces, and publish optional unlisted links. ## Architecture The app is Cloudflare-first: Worker APIs, D1 metadata, R2 asset storage, Queues for import processing, Workflow orchestration, and CloudControl container-processing metadata. PlayCanvas renders optimized SOG assets in the browser. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces Production host: `https://spaces.topolo.app`. Staging host: `https://spaces.stg.topolo.us`. ## API Reference Authenticated users work through the app UI and service-owned `/api/*` routes. Public routes only expose explicitly enabled unlisted links. ## Auth and Permissions Topolo Auth controls access through the stable `topolo-spaces` service slug. Spaces are private by default and scoped to the authenticated organization. ## Data Ownership TopoloSpaces owns spatial metadata, assets, processing records, annotations, public-link state, and events. V1 does not capture raw photos or videos and does not train new splats from source media. ## Mobile Experience The checked-in mobile experience contract is **published** in `native_capability` mode. Its fallback route is `/spaces`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/spaces` uses `/api/spaces` with the `record.list` template and `spaces.spaces.list` data source. - `/spaces/:id` uses `/api/spaces/:id` with the `record.detail` template and `spaces.spaces.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Production uses Worker `topolo-spaces`. Staging uses Worker `topolo-spaces-staging`. ## Failure Modes - Imported PLY/ZIP files wait for the processor lane before they are viewable. - Unlisted public links work only after a ready runtime SOG exists. - Disabling publishing returns the space to private-only access. ## Debugging Use the internal TopoloSpaces handbook for operator checks, D1/R2 inspection, CloudControl target resolution, and staging QA persona verification. ## Use It Open [TopoloSpaces](https://spaces.topolo.app) for the human product surface. The [system handbook](/systems/topolo-spaces) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-spaces --json topolo actions --service topolo-spaces --json topolo actions capabilities --service topolo-spaces --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-spaces) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloSpaces and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloSpaces` `origin/staging` `e2021b370f0d` on 2026-07-27. - Reconciled this page against `apps/TopoloSpaces` `origin/staging` `77add00b796c` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloSpaces commits through 7dbee1b; reviewed 323 commits since 2026-05-14, including 7dbee1b chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); a600b90 Stop blocking startup on i18n readiness; 4f5f6a4 Adopt canonical Topolo typography; 5c22238 Split Spaces shell startup bundle. - 2026-05-12: TopoloSpaces v1 documented as an import-first private business app. ## Topolo Status Canonical URL: https://docs.topolo.app/applications/status Public overview of the Topolo status page and production health monitoring surface. ## What It Is Topolo Status is the public status page for Topolo production surface health. ## Architecture The Status Worker serves the public page, exposes read-only health data, runs scheduled production probes, records status history in D1, and alerts operators when repeated probe failures cross the configured threshold. ## Runtime Surfaces See `/systems/topolo-status` for the current host, Worker, and service metadata. ## API Reference The anonymous Status API is read-only and centered on status-page rendering, `GET /api/status`, and the `/api/health` healthcheck. Credential-scoped operators can additionally poll the fleet and manage incident or maintenance lifecycles through the published Topolo actions. ## Auth and Permissions The public status surface is read-only. `status:poll` gates manual polling and `status:write` gates incident and maintenance mutations; those records live in the service's platform-owned system workspace. ## Data Ownership Topolo Status owns status incidents, probe history, and aggregate production-health telemetry. It does not own the downstream product data for the services it monitors. ## Deployments Topolo Status deploys as the production `topolo-status` Worker serving `https://status.topolo.app`. ## Failure Modes - monitored endpoint outage, DNS failure, or false positive - D1 write failure for probe history - alert webhook delivery failure - route or Worker deployment drift ## Debugging Start with `/systems/topolo-status`, then check `https://status.topolo.app/api/health`, Worker logs, and recent status-history rows for the affected probe target. ## Use It Open [Topolo Status](https://status.topolo.app) for the human product surface. The [system handbook](/systems/topolo-status) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-status --json topolo actions --service topolo-status --json topolo actions capabilities --service topolo-status --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-status) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Status and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the public read surface and credential-scoped poll, incident, and maintenance actions against `origin/staging` on 2026-07-28. - Reconciled this page against `system-apps/TopoloStatus` `origin/staging` `7dc28d7f2ab5` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Added public application coverage on 2026-06-28 so the public Status system no longer relies only on internal handbook coverage. - Centralized Status app identity metadata on 2026-05-13 so runtime and CloudControl config no longer carry concrete app ids. - Added canonical system coverage on 2026-05-02 from the CloudControl manifest and package metadata so the Docs registry covers the public status and monitoring Worker. ## Topolo Success Canonical URL: https://docs.topolo.app/applications/success Public overview of Topolo Success in the Topolo application suite. ## What It Is Topolo Success is part of the Topolo business application suite. ## Architecture The application uses the shared Topolo shell and Topolo Auth boundary from the outset. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The scaffold baseline is live at `https://success.topolo.app`. ## API Reference The generated API baseline exposes authenticated workspace routes under `/api/*` and validates requests through Topolo Auth. ## Auth and Permissions Signed browser and API requests use Topolo Auth through the app id resolved from the stable `topolo-success` service slug. ## Data Ownership The generated baseline has no durable domain data yet. Future data must be organization-scoped at the backend boundary. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard/workspace`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`. - `/dashboard/workspace` uses `/api/widget` with the `record.detail` template and `success.workspace.summary` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments The scaffold baseline is live at `https://success.topolo.app`. ## Failure Modes - service registration and app routing can drift while the product is still planned - service slug resolution or deployment Auth-origin metadata can drift while the product is still planned - organization-scoped data models are not implemented until domain work begins ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Success](https://success.topolo.app) for the human product surface. The [system handbook](/systems/topolo-success) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-success --json topolo actions --service topolo-success --json topolo actions capabilities --service topolo-success --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-success) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Success and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 1 published route(s) against `apps/TopoloSuccess` `origin/staging` `00e4162aa834` on 2026-07-27. - Reconciled this page against `apps/TopoloSuccess` `origin/staging` `d40706517883` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloSuccess commits through 98dc18e; reviewed 303 commits since 2026-05-14, including 98dc18e chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 457b0c4 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); af53cd1 Stop blocking startup on i18n readiness; 1931224 Adopt canonical Topolo typography. - Centralized runtime app identity on 2026-05-13 so Success resolves the `topolo-success` slug instead of compiling concrete app ids. - Deployed Worker/static-assets baseline to `https://success.topolo.app` on 2026-04-23. - Scaffold generated on 2026-04-23 from `topolo apps scaffold`. ## Topolo Support Canonical URL: https://docs.topolo.app/applications/support Public overview of the Topolo support platform for internal operations and customer-organization ticket workflows. ## What It Is Topolo Support is the support platform for the Topolo ecosystem, used for both Topolo internal support operations and customer-organization ticket workflows. ## Architecture The application is a standalone Worker-hosted frontend at `support.topolo.app`. It relies on Topolo Auth for sign-in and requester-context reads, while ticket workflow state lives in the app’s own support-owned D1 schema. Public entry now uses the shared Auth-managed landing and login pages, and the signed console now uses the shared first-party shell and browser auth packages from `topolo-platform/packages` instead of active Support-local copies. The signed desk now follows the same responsive shared shell pattern as the other first-party apps, including the shared launcher and local command palette surfaces. The shared public copy, provider visibility, and accent colors for Support are Auth-owned configuration associated with the `topolo-support` service, and the same-origin `/api/auth/*` gateway is also the required path for shared launcher catalog reads. Signed access is tenant-scoped through explicit support workspaces and inboxes: Topolo operators can switch across workspaces, org operators can work only their own organization workspace, and requester-grade users can create and follow only their own public ticket threads. Support also keeps its own activity ledger, outbound notification outbox, signed inbound webhook ledger, and app-owned channel routing/sync state so ticket creation, replies, assignment changes, and provider callbacks remain auditable. Nexus owns the connected provider identity, lifecycle, errors, and credentials; Support retains only the stable Nexus reference and hydrates those fields live. A scheduled Worker retry loop now re-attempts due queued or failed notifications with backoff, so customer-facing delivery does not depend on a currently signed-in operator. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The primary runtime host is `https://support.topolo.app`, with a staging mirror at `https://support.stg.topolo.us`, public entry routes at `/` and `/login`, and signed routes for `/tickets`, `/tickets/:ticketId`, and `/macros`. ## API Reference Topolo Support owns a dedicated `/api/support/*` route family for workspace context, tickets, messages, per-ticket notification dispatch, and signed inbound webhook ingestion. Auth remains the source of truth for identity and service access only, and Nexus is the outbound email delivery layer for queued Support notifications. ## Auth and Permissions Topolo Support uses the shared Topolo browser auth client and Auth-managed service access under the canonical app id `app_topolo_support` in every environment. The Worker receives that id through `APP_ID`, injects it into the served HTML shell, and backend routes use the same binding before setting `X-App-ID`; staging seed routes separately use `TOPOLO_SEED_APP_ID=app_topolo_seed`. Browser login URL construction and callback completion delegate to the shared auth client, including one-time `sso_code` redemption; direct bearer-token callback URLs, `/sso?token=` bridge routes, and app-local `/sso/exchange` parser code are not supported. ## Data Ownership Topolo Support owns support workspaces, inbox metadata, tickets, message history, inbound webhook audit state, activity history, queued notification intents plus retry state, assignment state, SLA tracking, and workspace-scoped macros. Topolo Auth owns identity, organization, permission, and launcher metadata only, and Topolo Nexus owns the downstream email-provider delivery hop. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/tickets`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `tickets:read`, `tickets:write`, `macros:read`, `macros:write`. - `/tickets` uses `/api/support/tickets` with the `record.list` template and `support.tickets.list` data source. - `/tickets/:id` uses `/api/support/tickets/:id` with the `record.detail` template and `support.tickets.detail` data source. - `/macros` uses `/api/support/macros` with the `record.list` template and `support.macros.list` data source. - `/macros/:id` uses `/api/support/macros/:id` with the `record.detail` template and `support.macros.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Support deploys as the Cloudflare Worker `topolo-support` on `support.topolo.app`. Its staging mirror deploys separately as `topolo-support-staging` on `support.stg.topolo.us`, with staging builds injecting staging Auth and portal hosts. ## Failure Modes - the wrong Worker deployment or route serves `support.topolo.app` - the support-owned D1 binding is missing or misconfigured - the app bypasses Auth for requester context and drifts from the canonical identity source of truth - signed inbound provider calls reach Support without the configured webhook secret or with an invalid signature - queued outbound notifications cannot leave Support because no Nexus sender profile is available, the Support-to-Nexus service token is mismatched, or automated retries are not running - staging was deployed from a stale `dist/` bundle or without staging Auth/portal build variables ## Debugging Start with `/systems/topolo-support`, then verify the Worker deployment, support D1 binding, Auth session/context reads, inbound webhook audit rows, queued notification delivery metadata, and retry timestamps. ## Use It Open [Topolo Support](https://support.topolo.app) for the human product surface. The [system handbook](/systems/topolo-support) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-support --json topolo actions --service topolo-support --json topolo actions capabilities --service topolo-support --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-support) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Support and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled canonical Nexus connection ownership against `apps/TopoloSupport` staging commit `bcab37c4e46e` on 2026-08-01. Support retains channel routing/sync state and a stable connection reference; Nexus remains the sole provider identity, lifecycle, error, and credential authority. - Reconciled the application identity against the manifest, all Wrangler environments, Auth staging, and Auth production on 2026-08-01. All four surfaces resolve `topolo-support` to `app_topolo_support`; the retired production-specific id is not canonical documentation. - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 4 published route(s) against `apps/TopoloSupport` `origin/staging` `09b817e10143` on 2026-07-27. - Reconciled this page against `apps/TopoloSupport` `origin/staging` `9265c60d3a58` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloSupport commits through 3c3beb7; reviewed 85 commits since 2026-06-18, including 3c3beb7 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 2464c68 Stop blocking startup on i18n readiness; ea264b1 Adopt canonical Topolo typography; ced3913 Split Support startup bundle. - Replaced runtime Support Auth slug lookups on 2026-05-13 with deployment `APP_ID` and `TOPOLO_SEED_APP_ID` bindings so browser auth, shared shell, widget, seed, and backend Auth calls do not call Auth to discover stable app ids. - Isolated staging browser builds and runtime upstream requirements on 2026-04-30 so `support.stg.topolo.us` no longer depends on production Auth, portal, or Nexus fallbacks. - Removed the Support app-local login and callback exchange path on 2026-04-18 so sign-in URL construction and `/auth/callback` code redemption now rely on the shared Topolo browser auth client - Added dedicated Support-to-Nexus trusted service auth and scheduled outbox retries on 2026-04-15 so queued or failed customer-facing notifications now back off and retry automatically without relying on a signed-in operator - Added signed inbound webhook ingestion and Nexus-backed outbound notification delivery on 2026-04-15 so Support now records provider callbacks, retries queued per-ticket notifications from the signed desk, and hands actual email delivery off to Nexus - Added a support-owned communications ledger on 2026-04-15 so ticket creation, workflow updates, and replies now record activity events plus queued requester or agent notifications inside Support’s own data boundary - Introduced explicit support workspaces and inboxes on 2026-04-15 so customer organizations now land in a concrete workspace and inbox model instead of relying only on tenant-filtered queues, and workspace switching now drives which queue and macros the signed desk uses - Hardened Topolo Support to a tenant-scoped queue model on 2026-04-15 so signed users now see only the queues and replies appropriate to their Topolo or organization role, with guest/requester users limited to their own public ticket threads - Corrected the signed Support shell on 2026-04-15 so the app now follows the same responsive shared first-party shell composition and local command palette contract as the other Topolo apps instead of keeping a Support-local signed layout inside the shell container - Corrected the shared Support experience contract on 2026-04-15 so Auth now serves Support-specific landing/login copy and readable shared color tokens, while the local `/api/auth/*` gateway correctly forwards shared launcher catalog reads instead of returning 404s - Standardized Topolo Support public entry on the shared landing and login surfaces on 2026-04-15 so unauthenticated visitors now enter through the Auth-managed shared pages instead of a Support-specific public shell - Standardized Topolo Support on the shared first-party shell and browser package contract on 2026-04-15 so the signed desk now uses the shared launcher/shell/auth surfaces instead of the old Support-local package copies in the active build path - Created Topolo Support on 2026-04-13 as the dedicated internal support desk, replacing the old Admin placeholder route with a standalone application boundary - Switched Topolo Support to a Worker-with-assets deployment on 2026-04-13 after the Pages asset layer proved unreliable in production ## Topolo Survey Canonical URL: https://docs.topolo.app/applications/survey Public overview of Topolo Survey, the Topolo survey builder and public response collection application. ## What It Is Topolo Survey is the Topolo application for building surveys, publishing public collector links, and reviewing responses from an authenticated workspace. ## Architecture The application uses the shared Topolo shell and Topolo Auth for authenticated operator workflows. A Cloudflare Worker serves the workspace, public collector routes, and API surface, backed by an app-owned D1 database. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces - Shared landing page at `https://survey.topolo.app/` - Shared login page at `https://survey.topolo.app/login` - Shared auth callback at `https://survey.topolo.app/auth/callback` - Authenticated workspace at `https://survey.topolo.app/` once signed in - Public collector routes under `https://survey.topolo.app/public/:slug` - Authenticated admin APIs under `/api/surveys/*` - Public collector APIs under `/api/public/surveys/:slug*` ## API Reference The current production v1 exposes: - `GET /api/health` - `GET /api/bootstrap` - `GET/POST /api/surveys` - `GET/PATCH/DELETE /api/surveys/:id` - `GET /api/surveys/:id/responses` - `GET /api/surveys/:id/summary` - `GET /api/public/surveys/:slug` - `POST /api/public/surveys/:slug/responses` ## Auth and Permissions Authenticated browser and API requests use Topolo Auth through app id `app_RCOi7CJkwf7R`, supplied to the Worker as `APP_ID` rather than resolved through a runtime Auth slug lookup. Signed-out operators land on the shared Topolo landing and login screens before entering the workspace. Public collector routes do not require authentication and only expose published survey definitions plus response submission. ## Data Ownership Topolo Survey stores organization-scoped survey definitions and responses in its own D1 database. Public submission routes write into the owning organization only for the published survey slug being collected. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/surveys`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`, `workspace:write`. - `/surveys` uses `/api/surveys` with the `record.list` template and `survey.surveys.list` data source. - `/surveys/:id` uses `/api/surveys/:id` with the `record.detail` template and `survey.surveys.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Topolo Survey is deployed on Cloudflare Workers with Workers Static Assets at `https://survey.topolo.app`, with shared landing, login, and callback pages on the browser surface plus the authenticated survey workspace after sign-in. ## Failure Modes - a collector slug is published incorrectly or collides with another survey slug - public collector routes expose draft definitions instead of published survey data - response submission accepts malformed answers or writes outside the owning organization ## Debugging - use the internal handbook for operational detail - verify the system registry entry before deployment or service-registration changes - smoke the published collector GET and POST routes after deploy when survey collection behavior changes ## Use It Open [Topolo Survey](https://survey.topolo.app) for the human product surface. The [system handbook](/systems/topolo-survey) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-survey --json topolo actions --service topolo-survey --json topolo actions capabilities --service topolo-survey --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-survey) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Survey and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloSurvey` `origin/staging` `79a83af4e047` on 2026-07-27. - Reconciled this page against `apps/TopoloSurvey` `origin/staging` `93c41b6d7818` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Reconciled workspace verification on 2026-06-28 against apps/TopoloSurvey commits through 90eaab6; reviewed 383 commits since 2026-05-14, including 90eaab6 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 78df723 Stop blocking startup on i18n readiness; 92b6e48 Adopt canonical Topolo typography; 28e9fa0 Lazy load Survey shell. - Implemented the first production v1 with D1-backed surveys, public collectors, response capture, and response summary on 2026-04-23. - `npm run typecheck` - `npm test` - `npm run build` - `npm run validate` in TopoloDocs ## TopoloP2P Canonical URL: https://docs.topolo.app/applications/topolo-p2p Public overview of Topolo's cross-organization capability network for human and agent business actions and settlement. ## What It Is TopoloP2P is the Topolo network layer for organizations that want their people and agents to transact with other organizations safely. It turns a public directory of capabilities into a governed action rail with policy checks, approvals, ledgering, and payment settlement. ## Architecture Organizations publish capabilities through Topolo Developers. Other organizations discover those capabilities through TopoloOne and request work through TopoloP2P. Topolo Auth verifies the human or agent employee making the request, TopoloP2P applies org policy, TopoloOne handles approvals, and TopoloPay executes payment settlement when value needs to move. ## Runtime Surfaces The planned production host is `https://p2p.topolo.app`. The isolated staging host is `https://p2p.stg.topolo.us`. Public discovery is expected to appear through TopoloOne at `https://topolo.io/directory`. ## API Reference The public API is not generally available yet. The internal route contract is documented in `/internal/platform/p2p-protocol`. ## Auth and Permissions TopoloP2P uses Topolo Auth for organization identity, human employee identity, agent employee identity, grants, scopes, and approval policy. Agents can initiate requests, but organization policy decides whether the request is accepted automatically, needs human approval, or is rejected. The app resolves its Auth app identity from the `topolo-p2p` service slug at runtime. ## Data Ownership Topolo Auth owns workspace identity and accessible-workspace listing. TopoloP2P keeps identity-only workspace mirrors as foreign-key parents for workspace-scoped action, ledger, settlement, and audit rows; it cannot author workspace names or slugs. TopoloP2P owns cross-organization action requests, policy decisions, immutable ledger entries, settlement batches, and audit events. TopoloPay owns Stripe-backed settlement execution. Topolo Developers owns the source capability listings. ## Deployments TopoloP2P will deploy as a Cloudflare-backed first-party application. The canonical deployment metadata lives in the TopoloP2P system registry and CloudControl manifest. ## Failure Modes - a paid action executes without the organization's configured approval policy - an agent bypasses P2P and calls another organization's app directly - settlement state is inferred from P2P ledger state instead of TopoloPay payment state ## Debugging Start from the P2P request id. For money movement, inspect TopoloPay settlement state before debugging Stripe. ## Use It Open [TopoloP2P](https://p2p.topolo.app) for the human product surface. The [system handbook](/systems/topolo-p2p) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-p2p --json topolo actions --service topolo-p2p --json topolo actions capabilities --service topolo-p2p --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-p2p) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloP2P and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the Auth-owned workspace identity mirror and split deployment topology through `system-apps/TopoloP2P` `origin/staging` `9d220da3c416` on 2026-07-29; the retired aggregate migration/config paths are no longer part of the product contract. - Reconciled workspace verification on 2026-06-28 against system-apps/TopoloP2P commits through ec04075; reviewed 281 commits since 2026-05-14, including ec04075 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 1f0d15f Split P2P workspace tab bundles; ca497d5 Adopt canonical Topolo typography; 6a1edb4 Roll out ui-kit capture startup split. - 2026-04-29 — Clarified the human-and-agent scope and recorded the isolated staging host for pre-production verification. - 2026-05-13 — Verified P2P runtime app identity is resolved from Auth by slug instead of hardcoded in browser or Worker config. - 2026-04-28 — Initial public P2P overview added for the planned cross-organization action and settlement network. ## TopoloSeed Canonical URL: https://docs.topolo.app/applications/topolo-seed TopoloSeed is an internal staging-only seed and load-test control plane and is not publicly available. TopoloSeed is an internal Topolo staging control plane for synthetic data, load simulation, timed bursts, and reset planning. It is not available as a public application and has no production deployment. ## What It Is TopoloSeed is an internal-only Topolo staging tool. It is not a customer-facing product. ## Architecture The application runs only in the Topolo staging Cloudflare account and resolves its Auth boundary through the `topolo-seed` service slug for operator access. ## Runtime Surfaces TopoloSeed has a staging-only host at `seed.stg.topolo.us`. It has no production host. ## API Reference The API is private to Topolo operators and is documented in the internal handbook. ## Auth and Permissions Access requires Topolo internal seed permissions. ## Data Ownership TopoloSeed owns synthetic staging seed metadata and run evidence only. ## Deployments TopoloSeed deploys only to staging. ## Failure Modes The public-facing failure mode is accidental exposure. The deployment contract blocks production deployment. ## Debugging Topolo operators should use the internal handbook. ## Use It Open [TopoloSeed](https://seed.stg.topolo.us) for the human product surface. The [system handbook](/systems/topolo-seed) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-seed --json topolo actions --service topolo-seed --json topolo actions capabilities --service topolo-seed --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-seed) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloSeed and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled docs freshness on 2026-06-28 against system-apps/TopoloSeed through cfe4f39; latest commit reviewed was cfe4f39 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile), with recent context cfe4f39 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); 86a232d Stop blocking startup on i18n readiness; ec74a92 Adopt canonical Topolo typography. - Added the public internal-only notice on 2026-04-30. - Verified runtime Auth app identity resolution from the `topolo-seed` slug on 2026-05-13. ## Topolo Voice Canonical URL: https://docs.topolo.app/applications/voice Public overview of Topolo Voice in the Topolo application suite. ## What It Is Topolo Voice is the first-party telephony workspace for incoming calls, completed and missed outcomes, provider incidents, recordings, transcripts, and voicemails. ## Architecture The application uses the shared Topolo shell and Topolo Auth boundary. Its API persists organization-scoped call state before publishing typed notification events through Topolo Notify. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces The production baseline is live at `https://voice.topolo.app`; the exact notification workflow source is staging-first and awaiting deployment proof. ## API Reference The API exposes authenticated workspace operations plus incoming, completed, missed, provider-failure, recording, transcript, and voicemail transitions under `/api/*`. ## Auth and Permissions Signed browser and API requests use Topolo Auth through canonical app id `app_topolo_voice` and service slug `topolo-voice`. ## Data Ownership Topolo Auth owns Voice workspace identity and lifecycle. Voice owns the calls, provider incidents, recordings, transcripts, and voicemails scoped to those workspaces in D1. Artifact URLs and telephone identifiers are confidential data and remain behind signed workspace access. ## Notifications Voice publishes seven typed notification contracts for incoming, completed, and missed calls; provider failures; ready recordings and transcripts; and received voicemails. Each event is emitted only after its Voice-owned D1 transition is durable, so an unavailable delivery channel cannot roll back telephony state. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/dashboard/workspace`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `workspace:read`. - `/dashboard/workspace` uses `/api/widget` with the `record.detail` template and `voice.workspace.summary` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments The scaffold baseline is live at `https://voice.topolo.app`. ## Failure Modes - service registration or app routing drifts from canonical identity `app_topolo_voice` - the workflow migration is missing from the deployed D1 database - the API service credential cannot write events to Notify ## Debugging - use the matching internal handbook for operational details - verify the system registry entry before deployment or service-registration changes ## Use It Open [Topolo Voice](https://voice.topolo.app) for the human product surface. The [system handbook](/systems/topolo-voice) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-voice --json topolo actions --service topolo-voice --json topolo actions capabilities --service topolo-voice --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-voice) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover Topolo Voice and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the 2026-07-28 fleet audit closure against the source-pinned action, route, workspace, package, and test evidence; no unrepresented human-facing capability was found. - Verified the native_capability mobile experience contract and its 1 published route(s) against `apps/TopoloVoice` `origin/staging` `a69c1c45d516` on 2026-07-27. - Reconciled this page against `apps/TopoloVoice` `origin/staging` `d99848dbc310` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Completed seven published, durable Voice notification workflows on 2026-07-20 at staging commit `41b1838c001c0cfa975864a1f2be1bf3c11f3bdd`; source, migration, action, coverage, and registry gates passed. Live staging deployment proof remains pending. - Reconciled workspace verification on 2026-06-28 against apps/TopoloVoice commits through a39c377; reviewed 299 commits since 2026-05-14, including a39c377 chore(deps): roll @topolo-io/* pins to latest (fleet currency self-heal); 8387252 chore(deps): refresh @topolo-io/app-shell pins (package.json + lockfile); f593637 Stop blocking startup on i18n readiness; 2556f36 Adopt canonical Topolo typography. - Corrected public Voice authorization language on 2026-05-07 so voice profile use is governed by Agent/Auth likeness authorization rather than GDPR-style Consent. - Added public synthetic voice-profile ownership coverage on 2026-05-07. - Deployed Worker/static-assets baseline to `https://voice.topolo.app` on 2026-04-23. - Scaffold generated on 2026-04-23 from `topolo apps scaffold`. ## Topolo Web Canonical URL: https://docs.topolo.app/applications/web Build, preview, quality-check, publish, and recover responsive websites through a typed agent workflow. ## What It Is Topolo Web is a website studio and publishing runtime. Human users can work in the browser studio; Codex, Claude, and other authenticated agents can use the same product through credential-scoped actions published by Topolo Developers. The agent interface is repository-independent. It publishes the complete site-content JSON Schema, renderer-backed block catalog, required responsive viewports, a full example, deterministic quality findings, preview/public URLs, publish preflight, immutable versions, and recovery actions. ## Architecture Topolo Web separates its authenticated studio and control-plane API from the public site runtime. Topolo Developers owns publication and credential-scoped projection of machine actions; Topolo Auth supplies identity, organization context, service permissions, and API-key resource bindings. Topolo Web remains the target-owned authorization, site-data, rendering, quality, versioning, and domain boundary. ## Workspace Management The shared Topolo workspace control reads and manages app-scoped workspace identity through Topolo Auth: authenticated users can list, create, rename, choose a default, and delete an eligible workspace. Workspace IDs and slugs remain stable and exactly one default is explicit. The selected platform workspace scopes this application's app-owned records; the app retains only domain-specific deletion guards for default or non-empty workspaces. ## Runtime Surfaces - `https://web.topolo.app` — authenticated website studio - `https://web-api.topolo.app` — credential-protected site control plane - `https://sites.topolo.app` — public site runtime ## API Reference Agents should use the Topolo Developers action catalog described below. The action definitions publish the exact routes and schemas needed by CLI and MCP clients, so callers do not need to construct control-plane URLs directly. Open any Web contract in the [Agent Actions reference](/reference/actions?service=topolo-web), or follow the exact `docsUrl` returned by action discovery. ## Workspace management The authenticated studio exposes workspace settings from the shared workspace switcher. Users with the matching permissions can create and rename workspaces, choose the default workspace, and delete an empty non-default workspace. Renaming preserves the workspace's stable id and slug; changing the default is a separate operation. Agents can use the same declared actions: | Action | Permission | Behavior | | --- | --- | --- | | `app_topolo_web.workspaces.list` | `workspace:read` | List the caller's accessible Topolo Web workspaces | | `app_topolo_web.workspaces.create` | `workspace:write` | Create a workspace after confirmation | | `app_topolo_web.workspaces.rename` | `workspace:write` | Change the display name without changing the stable slug | | `app_topolo_web.workspaces.default.set` | `workspace:write` | Select the default workspace for the organization | | `app_topolo_web.workspaces.delete` | `workspace:delete` | Delete an empty non-default workspace after destructive confirmation | Mutation calls require the exact target `workspace` resource context. Auth validates access before Topolo Web applies its product-owned lifecycle rules. ## Capability discovery Start with the capability action instead of constructing a site from memory: ```bash topolo actions capabilities --service web --json topolo actions get app_topolo_web.sites.capabilities.get --json ``` `sites.capabilities.get` returns: - the current public contract version - canonical site-content and build-input schemas - allowed block types, fields, presentations, and presentation intent descriptions - canonical examples for every supported site intent - audience-specific composition recipes with a visual thesis, ordered content plan, interaction thesis, and failure modes to avoid - mobile, tablet, desktop, and 4K QA viewports - the ordered build and publication workflow Do not add fields or block types that are absent from the returned contract. ## Composition contract Supported blocks publish renderer-backed `presentations` in the returned block catalog. A presentation changes the composition and hierarchy of a block, not only its border or background. Every option includes a description of its intended use. Use only a value declared for that block; validation and write actions reject cross-block presentation values. The current composition families include: | Presentation | Intended use | | --- | --- | | `columns` | Cardless accent columns with section copy beside the items | | `mosaic` | An asymmetric editorial hierarchy for feature and application grids | | `ruled` | Numbered proof points separated by rules | | `divided` | A high-contrast metric band | | `editorial` | An asymmetric, magazine-like composition for heroes, stories, and image narratives | | `manifesto` | An oversized defining statement for a story block | | `spotlight` | One dominant customer quote with supporting testimonials | | `poster` | A media-led hero or image moment with copy integrated into the frame | | `tiers` | Horizontal pricing rows for plan comparison | | `split` | Section copy beside a structured comparison surface | | `timeline` | Numbered chronological or process content | | `annotated` | Dense source or legal references with annotations | | `cards` | A balanced responsive card grid when equal emphasis is intentional | For presentations whose block-catalog entry has `supportsItemsPlacement=true`, set `style.itemsPlacement` to `left` or `right` to reverse the relationship between section copy and repeated items. `style.imagePlacement` controls the copy/media relationship on supported hero and image compositions, as well as media and captions inside image frames. Both fields can be overridden at the declared responsive breakpoints. ## Composition recipes and quality The returned `compositionRecipes` cover platform, venture-investor, angel-investor, partner-channel, and marketplace-developer narratives. Recipes are planning guidance, not fixed templates: preserve the recipe's audience and visual thesis while adapting the content plan to verified material and the available assets. Do not build a long page by cloning one feature-card section and changing the nouns. Quality reports flag: - `composition_repetition` when one visual family dominates a long page - `composition_media_thin` when a long page lacks purposeful media-bearing sections - `composition_layout_flat` when a long page never uses structural layout blocks - `section_presentation_invalid` when a block persists a presentation it does not declare The first three findings are composition warnings that require visual judgement; the last is a blocking contract error. Agents must still inspect the whole page at every required viewport because a valid schema cannot prove that copy length, art direction, crop, spacing, or rhythm is good. Composition is part of the public contract. An agent should discover it from `sites.capabilities.get`, choose deliberately from the selected block's `presentations`, validate the complete payload, and visually inspect the result at every returned viewport. Do not infer a presentation from its name or use a presentation on a block that does not declare it. ## Build workflow 1. Call `sites.capabilities.get` and construct only declared content. 2. Call `sites.validate` with the complete site and content payload. This is a read-only POST and does not persist data. 3. Validate and plan `sites.build` locally, then execute it with `publish=false` after confirmation. 4. Read `sites.preview.get` and `sites.quality.get`. 5. Inspect the draft at every required viewport. Resolve every blocking quality issue. 6. Call `sites.publish.preflight`. Continue only when `canPublish=true`. 7. Plan and confirm `sites.publish`. 8. Open the returned public URL and confirm the returned immutable version is active. The primary action ids are: | Action | Behavior | | --- | --- | | `app_topolo_web.sites.capabilities.get` | Read schema, catalog, examples, composition recipes, viewports, and workflow | | `app_topolo_web.sites.validate` | Validate content and quality without persistence | | `app_topolo_web.sites.build` | Create one site and draft content; optionally publish | | `app_topolo_web.sites.preview.get` | Read stable draft/public URLs and required viewports | | `app_topolo_web.sites.quality.get` | Read deterministic quality findings | | `app_topolo_web.sites.publish.preflight` | Check launch readiness without mutation | | `app_topolo_web.sites.publish` | Create and activate an immutable version | | `app_topolo_web.sites.versions.list` | List versions belonging to a site | | `app_topolo_web.sites.versions.restore` | Restore a selected version as a new active version | ## Responsive quality Topolo Web requires visual verification at the viewport widths returned by the capability and preview actions. Schema validity is necessary but does not prove that hierarchy, typography, media, navigation, or content density works on mobile and desktop. `sites.quality.get`, `sites.validate`, and `sites.publish.preflight` provide deterministic findings. The agent must also open the returned preview URL at each required viewport before publication. ## Publish and recover Publishing creates and activates an immutable version. Run `sites.publish.preflight` first, then plan `sites.publish` so the exact request, confirmation status, verification step, and rollback action are visible before execution. To recover, list versions for the same site, select a returned version id, validate and plan `sites.versions.restore`, confirm it, and verify the new active version at the returned public URL. Never use a version id copied from another site. ## Auth and Permissions The action catalog is filtered to the current credential. Read and validation actions require the published studio-read permission. Build, publish, and restore actions require their corresponding write permissions and explicit confirmation. Target-owned policy remains authoritative for the concrete organization, workspace, site, and version. ## Data Ownership Topolo Web owns sites, canonical content, draft state, quality findings, assets, domains, form submissions, events, agent sessions, and immutable published versions. Topolo Developers owns action publication; Topolo Auth owns credentials and service permission projection. ## Mobile Experience The checked-in mobile experience contract is **approved** in `native_capability` mode. Its fallback route is `/sites`, its offline policy is `read_through_cache`, and it requires organization context. Published permissions: `studio:read`, `studio:write`. - `/sites` uses `/api/studio/sites` with the `record.list` template and `web.sites.list` data source. - `/sites/:id` uses `/api/studio/sites/:id` with the `record.detail` template and `web.sites.detail` data source. The native clients consume this manifest as an explicit rendering contract. A `web` mode record intentionally opens the product web experience; `native_capability` publishes the listed native routes and actions. Do not infer unlisted native behavior. ## Deployments Production serves the studio, API, and public runtime from their separate hosts above. Staging uses `web.stg.topolo.us`, `web-api.stg.topolo.us`, and `sites.stg.topolo.us` with separate credentials and data. ## Failure Modes - capability/schema metadata is missing or older than the site payload - schema-valid content still fails responsive visual QA - publish is attempted before blocking quality findings are resolved - a site/version id is copied from another resource boundary - publication succeeds but the returned public URL/version is not verified - recovery is improvised instead of using a published immutable version ## Debugging Preserve the request id, action id, plan, schema errors, quality report, and returned site/version ids. Repeat the credential-scoped read or preflight action before escalating; do not replace a failed action with an inferred private endpoint. ## Use It Open [TopoloWeb](https://web.topolo.app) for the human product surface. The [system handbook](/systems/topolo-web) records its current hosts, ownership, Auth scopes, storage, deployment, failure modes, and machine artifact. Discover the credential-scoped automation surface before making an API call: ```bash topolo services --query topolo-web --json topolo actions --service topolo-web --json topolo actions capabilities --service topolo-web --json ``` Choose an action, inspect it with `topolo actions get --json`, then validate and plan a published example. The [Agent Actions reference](/reference/actions?service=topolo-web) exposes the same public schemas, effects, examples, verification, and recovery guidance. Example workflow: 1. Confirm the active identity and organization with `topolo whoami --json`. 2. Discover TopoloWeb and select one published action rather than guessing a route. 3. Inspect its input/output schemas and published example. 4. Validate and plan the exact payload; obtain confirmation for a mutation. 5. Execute and perform every published verification step. ## Change Log / Verification - Reconciled the Auth-owned workspace identity model and removal of Web's unapplied legacy migration tree through `apps/TopoloWeb` `origin/staging` `05c6f48c25dd` on 2026-07-28. - Verified the native_capability mobile experience contract and its 2 published route(s) against `apps/TopoloWeb` `origin/staging` `cb7aad9fc430` on 2026-07-27. - Reconciled this page against `apps/TopoloWeb` `origin/staging` `40c4ece2febc` on 2026-07-24 after reviewing every docs-relevant commit since its previous verification watermark. Dependency-only currency commits were checked by the fleet production-dependency gate and did not change this page's product contract. - Published the workspace-management contract on 2026-07-22 with shared-switcher UI, explicit default selection, safe deletion, dedicated permissions, and five declared workspace actions. - Expanded the composition contract on 2026-07-22 with asymmetric mosaics, quote spotlights, horizontal pricing tiers, reversible repeated-item placement, and matching CLI/MCP schemas. - Published the clean-room site contract on 2026-07-14 with canonical schemas, capability discovery, deterministic quality/preflight output, responsive QA viewports, typed publish/restore inputs and outputs, examples, verification URLs, and immutable-version recovery. # Source-derived contracts ## Agent source contract Human reference: https://docs.topolo.app/systems/topolo-agent Machine reference: https://docs.topolo.app/machine/systems/topolo-agent.json Source revisions: apps/TopoloAgent@0b6311b87b46f1890852ff3ec5c3d316f1c5b6bf Deploy targets: 2; implemented actions: 65; declared actions: 65; uncatalogued served routes: 0; mobile contracts: 1; route signals: 30. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### agents.list List configured workspace agents. Contract: GET /api/agents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: agents:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List agents.", "additionalProperties": true } ``` Effects: Reads state through GET /api/agents without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### agents.create Create a workspace agent. Contract: POST /api/agents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: agents:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "role": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "status": { "type": "string" }, "model": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "templateId": { "type": "string" }, "template_id": { "type": "string" }, "accountableUserId": { "type": "string" }, "accountable_user_id": { "type": "string" }, "executorType": { "type": "string" }, "executor_type": { "type": "string" }, "policyId": { "type": "string" }, "policy_id": { "type": "string" }, "serviceGrants": { "type": "array", "items": {} }, "service_grants": { "type": "array", "items": {} } }, "required": [ "name", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create agent.", "additionalProperties": true } ``` Effects: May change state through POST /api/agents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workflows.list List agent workflows. Contract: GET /api/workflows Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workflows:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List workflows.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workflows without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workflows.run Run an agent workflow by id. Contract: POST /api/workflows/{workflowId}/run Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runs:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workflowId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workflowId": { "type": "string", "minLength": 1 } }, "required": [ "workflowId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Run workflow.", "additionalProperties": true } ``` Effects: May change state through POST /api/workflows/{workflowId}/run. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### approvals.list List pending agent approvals. Contract: GET /api/approvals Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List approvals.", "additionalProperties": true } ``` Effects: Reads state through GET /api/approvals without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### approvals.get Get one approval request in the current organization. Contract: GET /api/approvals/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/approvals/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### approvals.respond Call POST /api/approvals/{id}/respond. Contract: POST /api/approvals/{id}/respond Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: approvals:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "decision": "approved" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "decision": { "type": "string", "enum": [ "approved", "rejected" ] }, "note": { "type": "string" } }, "required": [ "id", "decision" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Approvals Respond.", "additionalProperties": true } ``` Effects: May change state through POST /api/approvals/{id}/respond. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### reports.list List generated agent reports. Contract: GET /api/reports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List reports.", "additionalProperties": true } ``` Effects: Reads state through GET /api/reports without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### monitors.run Run a configured monitor by id. Contract: POST /api/monitors/{monitorId}/run Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runs:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "monitorId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "monitorId": { "type": "string", "minLength": 1 } }, "required": [ "monitorId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Run monitor.", "additionalProperties": true } ``` Effects: May change state through POST /api/monitors/{monitorId}/run. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### threads.list List agent threads. Contract: GET /api/threads Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List threads.", "additionalProperties": true } ``` Effects: Reads state through GET /api/threads without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### threads.create Create an agent thread. Contract: POST /api/threads Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "appScope": [ "example" ], "threadKind": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "appScope": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "threadKind": { "type": "string" }, "appSlug": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create thread.", "additionalProperties": true } ``` Effects: May change state through POST /api/threads. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### agents.get Call GET /api/agents/{id}. Contract: GET /api/agents/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: agents:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Agents Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/agents/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### agents.update Call PATCH /api/agents/{id}. Contract: PATCH /api/agents/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: agents:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "role": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "model": { "type": "string" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "accountableUserId": { "type": "string" }, "accountable_user_id": { "type": "string" }, "executorType": { "type": "string" }, "executor_type": { "type": "string" }, "policyId": { "type": "string" }, "policy_id": { "type": "string" }, "serviceGrants": { "type": "array", "items": {} }, "service_grants": { "type": "array", "items": {} } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Agents Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/agents/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### agents.runs.list Call GET /api/agents/{id}/runs. Contract: GET /api/agents/{id}/runs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: agents:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Agents Runs List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/agents/{id}/runs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### agents.runs.create Call POST /api/agents/{id}/runs. Contract: POST /api/agents/{id}/runs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runs:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "output": { "type": "string" }, "duration_ms": { "type": "number" }, "log": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Agents Runs Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/agents/{id}/runs. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### artifacts.list Call GET /api/artifacts. Contract: GET /api/artifacts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Artifacts List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/artifacts without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### connectors.list Call GET /api/connectors. Contract: GET /api/connectors Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Connectors List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/connectors without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### connectors.get Call GET /api/connectors/{id}. Contract: GET /api/connectors/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Connectors Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/connectors/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### inbox.list Call GET /api/inbox. Contract: GET /api/inbox Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Inbox List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/inbox without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### intakes.list Call POST /api/intakes. Contract: POST /api/intakes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "orgName": "example", "draftProfile": { "orgName": "example", "industry": "example", "businessSummary": "example" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "orgName": { "type": "string" }, "draftProfile": { "type": "object", "properties": { "orgName": { "type": "string" }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Intakes List.", "additionalProperties": true } ``` Effects: May change state through POST /api/intakes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### intakes.get Call GET /api/intakes/{id}. Contract: GET /api/intakes/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Intakes Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/intakes/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### intakes.messages.create Call POST /api/intakes/{id}/messages. Contract: POST /api/intakes/{id}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "operator", "assistant", "system" ] }, "content": { "type": "string" }, "currentStep": { "type": "string" }, "draftProfile": { "type": "object", "properties": { "orgName": { "type": "string" }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Intakes Messages Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/intakes/{id}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### intakes.complete Call POST /api/intakes/{id}/complete. Contract: POST /api/intakes/{id}/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "profile": { "type": "object", "properties": { "orgName": { "type": "string" }, "industry": { "type": "string" }, "businessSummary": { "type": "string" }, "targetCustomer": { "type": "string" }, "revenueModel": { "type": "string" }, "primaryGoals": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredApps": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "brandVoice": { "type": "string" }, "operatorNotes": { "type": "string" } }, "additionalProperties": false } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Intakes Complete.", "additionalProperties": true } ``` Effects: May change state through POST /api/intakes/{id}/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### monitors.list Call GET /api/monitors. Contract: GET /api/monitors Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Monitors List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/monitors without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### person_profiles.list Call GET /api/person-profiles. Contract: GET /api/person-profiles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "visibility": "private", "includeArchived": "true" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "includeArchived": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/person-profiles without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### person_profiles.create Call POST /api/person-profiles. Contract: POST /api/person-profiles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "displayName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subjectUserId": { "type": "string" }, "ownerUserId": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "linkedPersonaId": { "type": "string" }, "linkedAgentId": { "type": "string" }, "voiceProfileId": { "type": "string" }, "writingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "speakingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "personaRules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "usagePolicy": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "authorizationEvidence": { "type": "array", "items": {} }, "displayName": { "type": "string", "minLength": 1 } }, "required": [ "displayName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/person-profiles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### person_profiles.get Call GET /api/person-profiles/{id}. Contract: GET /api/person-profiles/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/person-profiles/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### person_profiles.update Call PATCH /api/person-profiles/{id}. Contract: PATCH /api/person-profiles/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "subjectUserId": { "type": "string" }, "ownerUserId": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "linkedPersonaId": { "type": "string" }, "linkedAgentId": { "type": "string" }, "voiceProfileId": { "type": "string" }, "writingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "speakingStyle": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "personaRules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "usagePolicy": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "authorizationEvidence": { "type": "array", "items": {} } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/person-profiles/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### person_profiles.delete Call DELETE /api/person-profiles/{id}. Contract: DELETE /api/person-profiles/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/person-profiles/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### person_profiles.sources.create Call POST /api/person-profiles/{id}/sources. Contract: POST /api/person-profiles/{id}/sources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "sourceKind": "example", "sourceLabel": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sourceUrl": { "type": "string" }, "knowledgeDocumentId": { "type": "string" }, "authorizationEvidenceId": { "type": "string" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "id": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "minLength": 1 }, "sourceLabel": { "type": "string", "minLength": 1 } }, "required": [ "id", "sourceKind", "sourceLabel" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles Sources Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/person-profiles/{id}/sources. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### person_profiles.style_snapshots.create Call POST /api/person-profiles/{id}/style-snapshots. Contract: POST /api/person-profiles/{id}/style-snapshots Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "facet": "example", "summary": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "facet": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "styleRules": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "confidence": { "type": "number" }, "sourceCount": { "type": "number" } }, "required": [ "id", "facet", "summary" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles Style Snapshots Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/person-profiles/{id}/style-snapshots. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### person_profiles.preview Call POST /api/person-profiles/{id}/preview. Contract: POST /api/person-profiles/{id}/preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brief": { "type": "string" }, "prompt": { "type": "string" }, "mode": { "type": "string", "enum": [ "email", "chat", "brief", "post" ] }, "audience": { "type": "string" }, "channel": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Person Profiles Preview.", "additionalProperties": true } ``` Effects: May change state through POST /api/person-profiles/{id}/preview. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### personas.list Call GET /api/personas. Contract: GET /api/personas Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "visibility": "private", "includeArchived": "true" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "includeArchived": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Personas List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/personas without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### personas.create Call POST /api/personas. Contract: POST /api/personas Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "persona": { "type": "string" }, "pointOfView": { "type": "string", "enum": [ "first", "third" ] }, "point_of_view": { "type": "string", "enum": [ "first", "third" ] }, "targetAudience": { "type": "string" }, "target_audience": { "type": "string" }, "tone": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "voice": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "avatar": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "modelRouting": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "model_routing": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "isDefault": { "type": "boolean" }, "is_default": { "type": "boolean" }, "isArchived": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "doList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "do_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dontList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dont_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "bannedPhrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "banned_phrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredVocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferred_vocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Personas Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/personas. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### personas.get Call GET /api/personas/{id}. Contract: GET /api/personas/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Personas Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/personas/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### personas.update Call PATCH /api/personas/{id}. Contract: PATCH /api/personas/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "persona": { "type": "string" }, "pointOfView": { "type": "string", "enum": [ "first", "third" ] }, "point_of_view": { "type": "string", "enum": [ "first", "third" ] }, "targetAudience": { "type": "string" }, "target_audience": { "type": "string" }, "tone": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "voice": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "avatar": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "modelRouting": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "model_routing": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "visibility": { "type": "string", "enum": [ "private", "workspace" ] }, "isDefault": { "type": "boolean" }, "is_default": { "type": "boolean" }, "isArchived": { "type": "boolean" }, "is_archived": { "type": "boolean" }, "doList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "do_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dontList": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "dont_list": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "bannedPhrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "banned_phrases": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferredVocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] }, "preferred_vocabulary": { "anyOf": [ { "minItems": 1, "type": "array", "items": { "type": "string" } }, { "type": "string", "minLength": 1 } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Personas Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/personas/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### personas.delete Call DELETE /api/personas/{id}. Contract: DELETE /api/personas/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Personas Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/personas/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### personas.set_default Call POST /api/personas/{id}/default. Contract: POST /api/personas/{id}/default Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Personas Set Default.", "additionalProperties": true } ``` Effects: May change state through POST /api/personas/{id}/default. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### agent_thread.get Call GET /api/agent-thread. Contract: GET /api/agent-thread Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Agent Thread Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/agent-thread without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### agent_sessions.state Get the transcript and pending approval state for an agent session. Contract: GET /api/agent-session/{threadId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "threadId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 } }, "required": [ "threadId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/agent-session/{threadId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### agent_sessions.message Run a message turn in a workspace-scoped agent session. Contract: POST /api/agent-session/{threadId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "threadId": "example", "type": "message", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "message" }, "content": { "type": "string", "minLength": 1 }, "personaId": { "type": "string", "minLength": 1 } }, "required": [ "threadId", "type", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/agent-session/{threadId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### agent_sessions.approve Approve or reject a pending agent-session tool call. Contract: POST /api/agent-session/{threadId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "threadId": "example", "type": "approve", "approvalId": "example", "decision": "approve" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "const": "approve" }, "approvalId": { "type": "string", "minLength": 1 }, "decision": { "type": "string", "enum": [ "approve", "reject" ] } }, "required": [ "threadId", "type", "approvalId", "decision" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/agent-session/{threadId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### agent_thread.create Call POST /api/agent-thread. Contract: POST /api/agent-thread Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1 } }, "required": [ "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Agent Thread Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/agent-thread. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### agent_thread.stream Call POST /api/agent-thread/stream. Contract: POST /api/agent-thread/stream Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runs:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1 } }, "required": [ "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Agent Thread Stream.", "additionalProperties": true } ``` Effects: May change state through POST /api/agent-thread/stream. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### threads.get Call GET /api/threads/{id}. Contract: GET /api/threads/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/threads/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### threads.update Call POST /api/threads/{id}. Contract: POST /api/threads/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "id", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Update.", "additionalProperties": true } ``` Effects: May change state through POST /api/threads/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### threads.stream Call POST /api/threads/{id}/stream. Contract: POST /api/threads/{id}/stream Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runs:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "id", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Stream.", "additionalProperties": true } ``` Effects: May change state through POST /api/threads/{id}/stream. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### threads.import_website Call POST /api/threads/{id}/import-website. Contract: POST /api/threads/{id}/import-website Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: knowledge:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 } }, "required": [ "id", "url" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Import Website.", "additionalProperties": true } ``` Effects: May change state through POST /api/threads/{id}/import-website. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### threads.reset_onboarding Call POST /api/threads/{id}/reset-onboarding. Contract: POST /api/threads/{id}/reset-onboarding Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Reset Onboarding.", "additionalProperties": true } ``` Effects: May change state through POST /api/threads/{id}/reset-onboarding. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### threads.attachments.list Call GET /api/threads/{id}/attachments. Contract: GET /api/threads/{id}/attachments Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Attachments List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/threads/{id}/attachments without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### threads.attachments.create Call POST /api/threads/{id}/attachments. Contract: POST /api/threads/{id}/attachments Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "scope": { "type": "string", "enum": [ "thread", "global" ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Attachments Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/threads/{id}/attachments. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### threads.attachments.download Call GET /api/threads/{id}/attachments/{attachmentId}/download. Contract: GET /api/threads/{id}/attachments/{attachmentId}/download Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "attachmentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "attachmentId": { "type": "string", "minLength": 1 } }, "required": [ "id", "attachmentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Threads Attachments Download.", "additionalProperties": true } ``` Effects: Reads state through GET /api/threads/{id}/attachments/{attachmentId}/download without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### work_feed.list Call GET /api/work-feed. Contract: GET /api/work-feed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Work Feed List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/work-feed without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workflows.get Call GET /api/workflows/{id}. Contract: GET /api/workflows/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workflows:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Workflows Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workflows/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workflows.create Call POST /api/workflows. Contract: POST /api/workflows Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workflows:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "templateSlug": "example", "autoRun": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templateSlug": { "type": "string" }, "autoRun": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Workflows Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workflows. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Delete an empty, non-default Agent workspace. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.data.export Export organization-authored Agent data across D1 and external storage metadata without provider credentials or binary objects. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase organization-authored Agent data after active work is stopped and literal ERASE confirmation is provided. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "example", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace.get Call GET /api/workspace. Contract: GET /api/workspace Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Workspace Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspace without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.profile.update Update the operating profile for the current workspace. Contract: PATCH /api/workspace/profile Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "profile": { "orgName": "example", "industry": "example", "businessSummary": "example", "targetCustomer": "example", "revenueModel": "example", "primaryGoals": [ "example" ], "preferredApps": [ "example" ], "brandVoice": "example" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "profile": { "type": "object", "properties": { "orgName": { "type": "string", "minLength": 1 }, "industry": { "type": "string", "minLength": 1 }, "businessSummary": { "type": "string", "minLength": 1 }, "targetCustomer": { "type": "string", "minLength": 1 }, "revenueModel": { "type": "string", "minLength": 1 }, "primaryGoals": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "preferredApps": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "brandVoice": { "type": "string", "minLength": 1 }, "operatorNotes": { "type": "string" } }, "required": [ "orgName", "industry", "businessSummary", "targetCustomer", "revenueModel", "primaryGoals", "preferredApps", "brandVoice" ], "additionalProperties": false } }, "required": [ "profile" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspace/profile. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sdr.leads.ingest Create or update campaign-scoped SDR readiness state. Contract: POST /api/sdr/ingest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "leadKey": "example", "campaignKey": "example", "organization": { "canonicalName": "example" }, "contacts": [ { "fullName": "example", "title": "example", "email": "user@example.com" } ], "source": { "method": "example", "provider": "example" }, "enrichment": { "organizationFacts": [ { "type": "example", "value": "example" } ], "contactFacts": [ { "type": "example", "value": "example" } ] }, "proposedScores": { "icpFitScore": 1, "contactabilityScore": 1, "sourceConfidenceScore": 1 }, "qualityGate": { "status": "example" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "leadKey": { "type": "string", "minLength": 1 }, "campaignKey": { "type": "string", "minLength": 1 }, "crmCompanyId": { "type": "string" }, "crmContactId": { "type": "string" }, "organization": { "type": "object", "properties": { "canonicalName": { "type": "string", "minLength": 1 }, "domain": { "type": "string" }, "website": { "type": "string" }, "phone": { "type": "string" }, "country": { "type": "string" }, "city": { "type": "string" }, "address": { "type": "string" }, "linkedinUrl": { "type": "string" }, "industry": { "type": "string" }, "size": { "type": "string" } }, "required": [ "canonicalName" ], "additionalProperties": false }, "contacts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "fullName": { "type": "string" }, "title": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": "string" }, "whatsapp": { "type": "string" }, "linkedinUrl": { "type": "string" }, "externalProfileUrl": { "type": "string" }, "sourceConfidence": { "type": "number" }, "isPrimary": { "type": "boolean" } }, "additionalProperties": false } }, "source": { "type": "object", "properties": { "method": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "url": { "type": "string" }, "query": { "type": "string" }, "market": { "type": "string" }, "discoveredAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "required": [ "method", "provider" ], "additionalProperties": false }, "enrichment": { "type": "object", "properties": { "organizationFacts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "value": {}, "sourceUrl": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "type", "value" ], "additionalProperties": false } }, "contactFacts": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "value": {}, "sourceUrl": { "type": "string" }, "confidence": { "type": "number" } }, "required": [ "type", "value" ], "additionalProperties": false } } }, "additionalProperties": false }, "proposedScores": { "type": "object", "properties": { "icpFitScore": { "type": "number" }, "contactabilityScore": { "type": "number" }, "sourceConfidenceScore": { "type": "number" }, "namedContactScore": { "type": "number" }, "overallOutboundScore": { "type": "number" } }, "additionalProperties": false }, "qualityGate": { "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "status" ], "additionalProperties": false }, "controls": { "type": "object", "properties": { "manualState": { "type": "string", "enum": [ "active", "paused", "stopped" ] } }, "additionalProperties": false }, "lifecycle": { "type": "object", "properties": { "replyReceivedAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "lastOutboundAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "nextActionAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "leadKey", "campaignKey", "organization", "contacts", "source", "enrichment", "proposedScores", "qualityGate" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/sdr/ingest. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sdr.leads.outbound_ready List leads that currently pass campaign, evidence, contactability, and suppression gates. Contract: GET /api/sdr/outbound-ready Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "campaign": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "campaign": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 250 } }, "required": [ "campaign" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/sdr/outbound-ready without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sdr.leads.get Get one campaign-scoped SDR lead and its current readiness state. Contract: GET /api/sdr/leads/{leadKey} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "leadKey": "example", "campaign": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "leadKey": { "type": "string", "minLength": 1 }, "campaign": { "type": "string", "minLength": 1 } }, "required": [ "leadKey", "campaign" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/sdr/leads/{leadKey} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sdr.leads.events.create Record outbound, reply, pause, stop, or resume state for an SDR lead. Contract: POST /api/sdr/leads/{leadKey}/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "leadKey": "example", "campaignKey": "example", "eventType": "outbound_sent" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "leadKey": { "type": "string", "minLength": 1 }, "campaignKey": { "type": "string", "minLength": 1 }, "eventType": { "type": "string", "enum": [ "outbound_sent", "reply_received", "paused", "stopped", "resumed" ] }, "channel": { "type": "string" }, "occurredAt": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "nextActionAt": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "leadKey", "campaignKey", "eventType" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/sdr/leads/{leadKey}/events. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Blog source contract Human reference: https://docs.topolo.app/systems/topolo-blog Machine reference: https://docs.topolo.app/machine/systems/topolo-blog.json Source revisions: apps/TopoloBlog@ea26b09a5159a13506f1bc6b020273fb1a9396a1 Deploy targets: 2; implemented actions: 37; declared actions: 42; uncatalogued served routes: 5; mobile contracts: 0; route signals: 17. ### widget.get Get the TopoloBlog widget summary. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "snapshot": { "type": "object", "properties": { "summary": { "type": "string" } }, "required": [ "summary" ], "additionalProperties": {} }, "actions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "link": { "type": "string" }, "primary": { "type": "boolean" } }, "required": [ "id", "label", "link" ], "additionalProperties": false } }, "appId": { "type": "string" }, "serviceName": { "type": "string" }, "lastUpdated": { "type": "string" } }, "required": [ "type", "snapshot", "actions", "appId", "serviceName", "lastUpdated" ], "additionalProperties": {} } } }, "required": [ "success", "widgets" ], "additionalProperties": false } ``` Effects: Reads widget data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### workspace.bootstrap Get the signed TopoloBlog workspace bootstrap payload. Contract: GET /api/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "user": { "type": "object", "properties": { "id": { "type": "string" } }, "required": [ "id" ], "additionalProperties": {} }, "organization": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "slug" ], "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "user", "organization" ], "additionalProperties": false } ``` Effects: Reads workspace data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### overview.get Get publishing counts, upcoming releases, and recent editorial work. Contract: GET /api/overview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "overview": { "type": "object", "properties": { "counts": { "type": "object", "properties": { "draft": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "scheduled": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "published": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "media": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "publications": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "draft", "scheduled", "published", "media", "publications" ], "additionalProperties": false }, "upcoming": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "recent": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "counts", "upcoming", "recent" ], "additionalProperties": false } }, "required": [ "overview" ], "additionalProperties": false } ``` Effects: Reads workspace data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### analytics.overview Get the shared Insights readership overview for this editorial workspace. Contract: GET /api/analytics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 30 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 90 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "data" ], "additionalProperties": {} } ``` Effects: Reads workspace data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### articles.list Search, filter, sort, and paginate articles in the selected editorial workspace. Contract: GET /api/articles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "maxLength": 160 }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "articles", "total", "nextCursor" ], "additionalProperties": false } ``` Effects: Reads article data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### articles.preview Render an unsaved article draft to the same HTML used by the published reader surface. Contract: POST /api/articles/preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "title": "Preview article", "body": [ { "type": "paragraph", "text": "Preview body." } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Article headline; renders as the page H1 and seeds the slug when slug is omitted." }, "slug": { "description": "URL path segment. Omit to derive it from the title.", "type": "string", "maxLength": 120 }, "publicationId": { "description": "Target publication id from publications.list. Omit to use the workspace default publication.", "type": "string", "minLength": 1 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "description": "Ordered article content as typed blocks (paragraph, heading, list, image, quote, divider, code, callout). Text fields accept inline markdown: **bold**, *italic*, `code`, [label](https://…).", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } }, "seriesName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string", "format": "uri" }, "authorName": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "title" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bodyHtml": { "type": "string" } }, "required": [ "bodyHtml" ], "additionalProperties": false } ``` Effects: Reads article data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### articles.get Get one article from the selected editorial workspace. Contract: GET /api/articles/{articleId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Reads article data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### articles.revisions.list List the immutable revisions for an article. Contract: GET /api/articles/{articleId}/revisions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "articleId": { "type": "string" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "snapshot": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId" ], "additionalProperties": false }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" } }, "required": [ "id", "articleId", "revisionNumber", "snapshot", "createdByUserId", "createdAt" ], "additionalProperties": false } } }, "required": [ "revisions" ], "additionalProperties": false } ``` Effects: Reads article data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### articles.revisions.restore Restore an immutable revision as a new unpublished article revision. Contract: POST /api/articles/{articleId}/revisions/{revisionNumber}/restore Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example", "revisionNumber": 2 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "revisionNumber": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "articleId", "revisionNumber" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.create Create a new draft article in the selected editorial workspace. Always yields a draft: to go live, request review, approve, then publish or schedule. Contract: POST /api/articles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "How we ship every week", "excerpt": "The release habits that keep our team shipping weekly without breaking production.", "body": [ { "type": "paragraph", "text": "Shipping weekly is a **habit**, not a heroic effort. This post covers the *three* practices that make it routine." }, { "type": "heading", "level": 2, "text": "Keep changes small" }, { "type": "list", "style": "unordered", "items": [ "**Small diffs:** easier to review and revert.", "**Feature flags:** decouple deploy from release — see [our guide](https://example.com/flags)." ] }, { "type": "quote", "text": "If a release is scary, do it more often.", "attribution": "Engineering handbook" }, { "type": "code", "language": "bash", "code": "git switch -c release/weekly\ngit push origin release/weekly" }, { "type": "callout", "tone": "info", "title": "Draft first", "text": "Creating an article always produces a draft. Request review, approve, then publish or schedule it." }, { "type": "divider" }, { "type": "heading", "level": 3, "text": "What we measure" }, { "type": "paragraph", "text": "Lead time, review latency, and the rollback count — tracked per `release` tag." } ], "tags": [ "engineering", "process" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Article headline; renders as the page H1 and seeds the slug when slug is omitted." }, "slug": { "description": "URL path segment. Omit to derive it from the title.", "type": "string", "maxLength": 120 }, "publicationId": { "description": "Target publication id from publications.list. Omit to use the workspace default publication.", "type": "string", "minLength": 1 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "description": "Ordered article content as typed blocks (paragraph, heading, list, image, quote, divider, code, callout). Text fields accept inline markdown: **bold**, *italic*, `code`, [label](https://…).", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } }, "seriesName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string", "format": "uri" }, "authorName": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "title" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.update Update an article and append an immutable revision. Provided fields replace their previous values (body is replaced whole, not merged), and any edit resets review status to draft. Contract: PATCH /api/articles/{articleId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example", "title": "Updated title", "body": [ { "type": "paragraph", "text": "Replaces the whole body: send the complete block array, not a fragment." } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 160, "description": "Article headline; renders as the page H1 and seeds the slug when slug is omitted." }, "slug": { "description": "URL path segment. Omit to derive it from the title.", "type": "string", "maxLength": 120 }, "publicationId": { "description": "Target publication id from publications.list. Omit to use the workspace default publication.", "type": "string", "minLength": 1 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "description": "Ordered article content as typed blocks (paragraph, heading, list, image, quote, divider, code, callout). Text fields accept inline markdown: **bold**, *italic*, `code`, [label](https://…).", "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } }, "seriesName": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string", "format": "uri" }, "authorName": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.delete Permanently delete an article and its immutable revisions from the selected editorial workspace. Contract: DELETE /api/articles/{articleId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "articleId": { "type": "string" } }, "required": [ "deleted", "articleId" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.review.request Submit the current article revision for editorial review. Contract: POST /api/articles/{articleId}/review/request Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.review.approve Approve the exact article revision currently under review. Approval is a prerequisite for publish and schedule, and is voided by any later edit. Contract: POST /api/articles/{articleId}/review/approve Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.review.changes.request Return an article under review to its author with changes requested. Contract: POST /api/articles/{articleId}/review/changes-requested Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.publish Publish the approved current revision immediately while retaining later edits as unpublished changes. Fails with article_not_approved unless the current revision has been approved via the review actions. Contract: POST /api/articles/{articleId}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.schedule Schedule the approved current revision for future publication. Fails with article_not_approved unless the current revision has been approved via the review actions. Contract: POST /api/articles/{articleId}/schedule Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example", "publishAt": "2026-08-20T09:00:00.000Z" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "publishAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Future release time as an ISO 8601 UTC datetime, e.g. 2026-08-20T09:00:00.000Z." } }, "required": [ "articleId", "publishAt" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.reschedule Replace the release time for the already scheduled revision. Contract: POST /api/articles/{articleId}/reschedule Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example", "publishAt": "2026-08-21T09:00:00.000Z" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 }, "publishAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$", "description": "Future release time as an ISO 8601 UTC datetime, e.g. 2026-08-20T09:00:00.000Z." } }, "required": [ "articleId", "publishAt" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.schedule.cancel Cancel the pending scheduled release without changing any currently published revision. Contract: POST /api/articles/{articleId}/schedule/cancel Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.unpublish Remove the currently published revision from public delivery while retaining editorial history. Contract: POST /api/articles/{articleId}/unpublish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.duplicate Create a new draft from an existing article without copying its publication state. Contract: POST /api/articles/{articleId}/duplicate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "article": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "publicationKey": { "type": "string" }, "publicationId": { "type": "string" }, "publicationName": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "seriesName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seriesPosition": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "seoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ogImageUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonicalUrl": { "type": "string" }, "authorName": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "draft", "in_review", "changes_requested", "approved" ] }, "reviewRequestedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "approvedByUserId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "approvedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduledRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedRevisionNumber": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "hasUnpublishedChanges": { "type": "boolean" }, "revisionNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdByUserId": { "type": "string" }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "publicationKey", "publicationId", "publicationName", "title", "slug", "excerpt", "body", "tags", "seriesName", "seriesPosition", "seoTitle", "seoDescription", "ogImageUrl", "canonicalUrl", "authorName", "status", "reviewStatus", "reviewRequestedAt", "approvedRevisionNumber", "approvedByUserId", "approvedAt", "scheduledFor", "scheduledRevisionNumber", "publishedAt", "publishedRevisionNumber", "hasUnpublishedChanges", "revisionNumber", "createdByUserId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "article" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### articles.checks.get Run SEO completeness, accessibility, and bounded broken-link checks for an article. Contract: GET /api/articles/{articleId}/checks Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "articleId": "article_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleId": { "type": "string", "minLength": 1 } }, "required": [ "articleId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "checks": { "type": "object", "properties": { "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string", "enum": [ "pass", "warning", "error" ] }, "message": { "type": "string" } }, "required": [ "id", "label", "status", "message" ], "additionalProperties": false } }, "links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "broken", "blocked" ] }, "statusCode": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "url", "status", "statusCode" ], "additionalProperties": false } }, "complete": { "type": "boolean" } }, "required": [ "checks", "links", "complete" ], "additionalProperties": false } }, "required": [ "checks" ], "additionalProperties": false } ``` Effects: Reads article data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### articles.bulk Apply one governed editorial operation to up to 100 selected articles. Contract: POST /api/articles/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "articleIds": [ "article_example" ], "operation": "request_review" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "articleIds": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "operation": { "type": "string", "enum": [ "request_review", "approve", "publish", "unpublish", "delete" ] } }, "required": [ "articleIds", "operation" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "articleId": { "type": "string" }, "success": { "type": "boolean" }, "error": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "articleId", "success", "error" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false } ``` Effects: Changes article state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### templates.list List reusable article templates in the selected editorial workspace. Contract: GET /api/templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "titlePattern": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "titlePattern", "excerpt", "body", "tags", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "templates" ], "additionalProperties": false } ``` Effects: Reads article template data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### templates.create Create a reusable article structure for the selected editorial workspace. Contract: POST /api/templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "Product announcement", "body": [ { "type": "paragraph", "text": "Opening." } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 320 }, "titlePattern": { "type": "string", "maxLength": 160 }, "excerpt": { "type": "string", "maxLength": 320 }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "maxItems": 12, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 48 } } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "titlePattern": { "type": "string" }, "excerpt": { "type": "string" }, "body": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "type": { "type": "string", "const": "paragraph" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "heading" }, "level": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 } ], "description": "Section level. The article title renders as the H1, so body headings start at 2." }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "level", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "list" }, "style": { "type": "string", "enum": [ "ordered", "unordered" ] }, "items": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } } }, "required": [ "type", "style", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "image" }, "assetId": { "type": "string", "minLength": 1, "description": "Blog media asset id. Upload the image first with media.upload; its response provides assetId and url." }, "url": { "type": "string", "format": "uri" }, "altText": { "type": "string", "maxLength": 320 }, "caption": { "type": "string", "maxLength": 320, "description": "Rendered verbatim below the image; inline markdown is NOT applied here." } }, "required": [ "type", "assetId", "url", "altText", "caption" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "quote" }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." }, "attribution": { "type": "string", "maxLength": 160 } }, "required": [ "type", "text", "attribution" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "divider" } }, "required": [ "type" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "code" }, "language": { "type": "string", "maxLength": 48 }, "code": { "type": "string", "minLength": 1 } }, "required": [ "type", "language", "code" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "const": "callout" }, "tone": { "type": "string", "enum": [ "info", "success", "warning" ] }, "title": { "type": "string", "maxLength": 120 }, "text": { "type": "string", "minLength": 1, "description": "Plain text with optional inline markdown: **bold**, *italic*, `code`, and [label](https://…) links. No other markdown is rendered." } }, "required": [ "type", "tone", "title", "text" ], "additionalProperties": false } ], "description": "One typed content block. An article body is an ordered array of these blocks — paragraph, heading (levels 2–3), list, image, quote, divider, code, and callout." } }, "tags": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "titlePattern", "excerpt", "body", "tags", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "template" ], "additionalProperties": false } ``` Effects: Changes article template state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### templates.delete Delete a reusable article template. Contract: DELETE /api/templates/{templateId} Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "templateId": "template_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templateId": { "type": "string", "minLength": 1 } }, "required": [ "templateId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "templateId": { "type": "string" } }, "required": [ "deleted", "templateId" ], "additionalProperties": false } ``` Effects: Changes article template state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### saved_searches.list List saved article search and sorting configurations. Contract: GET /api/saved-searches Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "searches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "query": { "type": "string" }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "query", "status", "reviewStatus", "sort", "order", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "searches" ], "additionalProperties": false } ``` Effects: Reads saved search data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### saved_searches.create Save an article query, workflow filter, and sort order. Contract: POST /api/saved-searches Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "Needs approval", "reviewStatus": "in_review" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "query": { "type": "string", "maxLength": 160 }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "query": { "type": "string" }, "status": { "type": "string", "enum": [ "all", "draft", "scheduled", "published" ] }, "reviewStatus": { "type": "string", "enum": [ "all", "draft", "in_review", "changes_requested", "approved" ] }, "sort": { "type": "string", "enum": [ "updatedAt", "title", "publishedAt" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "query", "status", "reviewStatus", "sort", "order", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "search" ], "additionalProperties": false } ``` Effects: Changes saved search state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### saved_searches.delete Delete a saved article search configuration. Contract: DELETE /api/saved-searches/{searchId} Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "searchId": "search_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "searchId": { "type": "string", "minLength": 1 } }, "required": [ "searchId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "searchId": { "type": "string" } }, "required": [ "deleted", "searchId" ], "additionalProperties": false } ``` Effects: Changes saved search state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### publications.list List configured publishing destinations for the selected workspace. Contract: GET /api/publications Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publications": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "publications" ], "additionalProperties": false } ``` Effects: Reads publication data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### publications.create Create a named publishing destination with a canonical base URL. Contract: POST /api/publications Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "Company blog", "baseUrl": "https://example.com/blog" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 320 }, "defaultSeoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "slug": { "type": "string", "maxLength": 63 } }, "required": [ "name", "baseUrl" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publication": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "publication" ], "additionalProperties": false } ``` Effects: Changes publication state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### publications.update Update a publication name, destination, description, and SEO defaults. Contract: PATCH /api/publications/{publicationId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "publicationId": "publication_example", "name": "Company blog", "baseUrl": "https://example.com/blog" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publicationId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "baseUrl": { "type": "string", "format": "uri" }, "description": { "type": "string", "maxLength": 320 }, "defaultSeoTitle": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "publicationId", "name", "baseUrl" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publication": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "publication" ], "additionalProperties": false } ``` Effects: Changes publication state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### publications.default.set Choose the publication used automatically for new articles. Contract: POST /api/publications/{publicationId}/default Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "publicationId": "publication_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publicationId": { "type": "string", "minLength": 1 } }, "required": [ "publicationId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publication": { "type": "object", "properties": { "id": { "type": "string" }, "organizationId": { "type": "string" }, "workspaceId": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "baseUrl": { "type": "string" }, "description": { "type": "string" }, "defaultSeoTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "defaultSeoDescription": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "articleCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "organizationId", "workspaceId", "name", "slug", "baseUrl", "description", "defaultSeoTitle", "defaultSeoDescription", "isDefault", "articleCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "publication" ], "additionalProperties": false } ``` Effects: Changes publication state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### publications.delete Delete an unused non-default publication. Contract: DELETE /api/publications/{publicationId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "publicationId": "publication_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "publicationId": { "type": "string", "minLength": 1 } }, "required": [ "publicationId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "publicationId": { "type": "string" } }, "required": [ "deleted", "publicationId" ], "additionalProperties": false } ``` Effects: Changes publication state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### media.list List reusable Blog media assets in the selected workspace. Contract: GET /api/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "altText": { "type": "string" }, "url": { "type": "string" }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "fileName", "contentType", "byteSize", "altText", "url", "usageCount", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "assets" ], "additionalProperties": false } ``` Effects: Reads media asset data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### media.upload Upload a reusable image to the Blog media library. The response asset provides the assetId and url an article image block requires. Contract: POST /api/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contentBase64": "iVBORw0KGgo=", "contentType": "image/png", "fileName": "example.png" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "enum": [ "image/gif", "image/jpeg", "image/png", "image/webp" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "altText": { "type": "string", "maxLength": 320 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "altText": { "type": "string" }, "url": { "type": "string" }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "fileName", "contentType", "byteSize", "altText", "url", "usageCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "asset" ], "additionalProperties": false } ``` Effects: Changes media asset state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### media.update Update alternative text for a Blog media asset. Contract: PATCH /api/media/{assetId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "assetId": "media_example", "altText": "A useful description" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "maxLength": 320 } }, "required": [ "assetId", "altText" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "asset": { "type": "object", "properties": { "id": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "byteSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "altText": { "type": "string" }, "url": { "type": "string" }, "usageCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "fileName", "contentType", "byteSize", "altText", "url", "usageCount", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "asset" ], "additionalProperties": false } ``` Effects: Changes media asset state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### media.delete Permanently delete a Blog media asset. Contract: DELETE /api/media/{assetId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "assetId": "media_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 } }, "required": [ "assetId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "assetId": { "type": "string" } }, "required": [ "deleted", "assetId" ], "additionalProperties": false } ``` Effects: Changes media asset state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### settings.get Get workspace-level editorial and SEO defaults. Contract: GET /api/settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "properties": { "editorialName": { "type": "string" }, "defaultAuthorName": { "type": "string" }, "defaultSeoTitle": { "type": "string" }, "defaultSeoDescription": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "editorialName", "defaultAuthorName", "defaultSeoTitle", "defaultSeoDescription", "updatedAt" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } ``` Effects: Reads workspace data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### settings.update Update workspace-level editorial and SEO defaults. Contract: PUT /api/settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "editorialName": "Editorial team", "defaultAuthorName": "Topolo", "defaultSeoTitle": "Company blog", "defaultSeoDescription": "News and perspectives from the team." } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "editorialName": { "type": "string", "maxLength": 100 }, "defaultAuthorName": { "type": "string", "maxLength": 100 }, "defaultSeoTitle": { "type": "string", "maxLength": 160 }, "defaultSeoDescription": { "type": "string", "maxLength": 320 } }, "required": [ "editorialName", "defaultAuthorName", "defaultSeoTitle", "defaultSeoDescription" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "properties": { "editorialName": { "type": "string" }, "defaultAuthorName": { "type": "string" }, "defaultSeoTitle": { "type": "string" }, "defaultSeoDescription": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "editorialName", "defaultAuthorName", "defaultSeoTitle", "defaultSeoDescription", "updatedAt" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } ``` Effects: Changes workspace state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### organizations.data.export Export all TopoloBlog articles and immutable revisions for the authenticated organization. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "organization_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "organizationId": { "type": "string" }, "credentialsIncluded": { "type": "boolean", "const": false }, "exportedAt": { "type": "string" }, "articles": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "workspace_id": { "type": "string" } }, "required": [ "id", "workspace_id" ], "additionalProperties": {} } }, "revisions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "article_id": { "type": "string" } }, "required": [ "id", "article_id" ], "additionalProperties": {} } } }, "required": [ "organizationId", "credentialsIncluded", "exportedAt", "articles", "revisions" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } ``` Effects: Reads organization data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission privacy:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### organizations.data.erase Erase all TopoloBlog articles and revisions for the authenticated organization after literal ERASE confirmation. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "organization_example", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "organizationId": { "type": "string" }, "erased": { "type": "boolean", "const": true } }, "required": [ "organizationId", "erased" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } ``` Effects: Changes organization state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission privacy:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ## Bytes source contract Human reference: https://docs.topolo.app/systems/topolo-bytes Machine reference: https://docs.topolo.app/machine/systems/topolo-bytes.json Source revisions: apps/TopoloBytes@a91022036b05b981e179e035971d2c85a4d04f7e Deploy targets: 2; implemented actions: 30; declared actions: 30; uncatalogued served routes: 0; mobile contracts: 1; route signals: 42. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### files.list List files and folders. Contract: GET /api/list Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "prefix": "example", "cursor": "example", "fileType": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prefix": { "type": "string" }, "cursor": { "type": "string" }, "fileType": { "type": "string" }, "sizeMin": { "type": "string" }, "sizeMax": { "type": "string" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "durationMin": { "type": "string" }, "durationMax": { "type": "string" }, "search": { "type": "string" }, "sortBy": { "type": "string" }, "sortOrder": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List files.", "additionalProperties": true } ``` Effects: Reads state through GET /api/list without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### files.search Search files by metadata or content. Contract: GET /api/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "prefix": "example", "cursor": "example", "fileType": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prefix": { "type": "string" }, "cursor": { "type": "string" }, "fileType": { "type": "string" }, "sizeMin": { "type": "string" }, "sizeMax": { "type": "string" }, "dateFrom": { "type": "string" }, "dateTo": { "type": "string" }, "durationMin": { "type": "string" }, "durationMax": { "type": "string" }, "search": { "type": "string" }, "sortBy": { "type": "string" }, "sortOrder": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Search files.", "additionalProperties": true } ``` Effects: Reads state through GET /api/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### files.upload_url.create Create a signed upload URL for a file. Contract: POST /api/upload-url Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "type": "example", "size": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "type": { "type": "string", "minLength": 1 }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 104857600 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "type", "size" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create upload URL.", "additionalProperties": true } ``` Effects: May change state through POST /api/upload-url. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### files.rename Rename a file. Contract: POST /api/rename Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "oldKey": "example", "newKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "oldKey": { "type": "string", "minLength": 1 }, "newKey": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "oldKey", "newKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Rename file.", "additionalProperties": true } ``` Effects: May change state through POST /api/rename. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### shares.list List file sharing links. Contract: GET /api/shares Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sharing:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "cursor": "example", "limit": 1, "scope": "org" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List shares.", "additionalProperties": true } ``` Effects: Reads state through GET /api/shares without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### shares.create Create a sharing link. Contract: POST /api/shares/create Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sharing:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "fileKeys": [ "example" ], "permissions": "view", "shareType": "single" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "permissions": { "type": "string", "enum": [ "view", "download" ] }, "shareType": { "type": "string", "enum": [ "single", "multiple", "zip" ] }, "password": { "type": "string" }, "expirationDays": { "type": "number" }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "fileKeys", "permissions", "shareType" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create share.", "additionalProperties": true } ``` Effects: May change state through POST /api/shares/create. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### bulk.organize Run bulk file organization. Contract: POST /api/bulk/organize Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipelines:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "rules": { "type": "by-date" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "rules": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "by-date", "by-type", "by-size", "custom" ] }, "pattern": { "type": "string" }, "conditions": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type" ], "additionalProperties": false }, "dryRun": { "type": "boolean" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "rules" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk organize files.", "additionalProperties": true } ``` Effects: May change state through POST /api/bulk/organize. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### shares.refresh_session Call POST /api/shares/refresh-session. Contract: POST /api/shares/refresh-session Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "shareId": "example", "fileKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shareId": { "type": "string", "minLength": 1 }, "fileKey": { "type": "string", "minLength": 1 } }, "required": [ "shareId", "fileKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares Refresh Session.", "additionalProperties": true } ``` Effects: May change state through POST /api/shares/refresh-session. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### shares.delete Call DELETE /api/shares/{shareId}. Contract: DELETE /api/shares/{shareId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sharing:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "shareId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "shareId": { "type": "string", "minLength": 1 } }, "required": [ "shareId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/shares/{shareId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### desktop.releases.latest Call GET /api/desktop/releases/latest. Contract: GET /api/desktop/releases/latest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Desktop Releases Latest.", "additionalProperties": true } ``` Effects: Reads state through GET /api/desktop/releases/latest without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### desktop.download Call GET /api/desktop/download. Contract: GET /api/desktop/download Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 } }, "required": [ "key" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Desktop Download.", "additionalProperties": true } ``` Effects: Reads state through GET /api/desktop/download without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### uploads.multipart.create Call POST /api/multipart/create. Contract: POST /api/multipart/create Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "contentType": { "type": "string" }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Uploads Multipart Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/multipart/create. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### uploads.multipart.sign Call POST /api/multipart/sign. Contract: POST /api/multipart/sign Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "uploadId": "example", "partNumbers": [ 1 ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "partNumbers": { "minItems": 1, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 10000 } }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "uploadId", "partNumbers" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Uploads Multipart Sign.", "additionalProperties": true } ``` Effects: May change state through POST /api/multipart/sign. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### uploads.multipart.complete Call POST /api/multipart/complete. Contract: POST /api/multipart/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "uploadId": "example", "parts": [ { "partNumber": 1, "etag": "example" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "parts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": 1, "maximum": 10000 }, "etag": { "type": "string", "minLength": 1 } }, "required": [ "partNumber", "etag" ], "additionalProperties": false } }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "uploadId", "parts" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Uploads Multipart Complete.", "additionalProperties": true } ``` Effects: May change state through POST /api/multipart/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### uploads.multipart.abort Call POST /api/multipart/abort. Contract: POST /api/multipart/abort Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "uploadId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "uploadId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Uploads Multipart Abort.", "additionalProperties": true } ``` Effects: May change state through POST /api/multipart/abort. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### files.delete_route Call DELETE /api/delete. Contract: DELETE /api/delete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "files": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "files": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "files" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Files Delete Route.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/delete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### files.bulk_rename Call POST /api/bulk/rename. Contract: POST /api/bulk/rename Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "fileKeys": [ "example" ], "pattern": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "pattern": { "type": "string", "minLength": 1 }, "options": { "type": "object", "properties": { "startIndex": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "findText": { "type": "string" }, "replaceText": { "type": "string" }, "addTimestamp": { "type": "boolean" }, "preserveExtension": { "type": "boolean" } }, "additionalProperties": false }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "fileKeys", "pattern" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Files Bulk Rename.", "additionalProperties": true } ``` Effects: May change state through POST /api/bulk/rename. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### folders.create_alt Call POST /api/folders/create. Contract: POST /api/folders/create Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: folders:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "folderPath": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderPath": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "folderPath" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Folders Create Alt.", "additionalProperties": true } ``` Effects: May change state through POST /api/folders/create. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### folder.rename_alt Call PUT /api/folder/rename. Contract: PUT /api/folder/rename Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: folders:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "oldPath": "example", "newPath": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "oldPath": { "type": "string", "minLength": 1 }, "newPath": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "oldPath", "newPath" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Folder Rename Alt.", "additionalProperties": true } ``` Effects: May change state through PUT /api/folder/rename. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### folder.delete_alt Call DELETE /api/folder/delete. Contract: DELETE /api/folder/delete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "query": { "folderPath": "example" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "object", "properties": { "folderPath": { "type": "string", "minLength": 1 }, "force": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "folderPath" ], "additionalProperties": false } }, "required": [ "query" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Folder Delete Alt.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/folder/delete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### folder.info.get Call GET /api/folder/info. Contract: GET /api/folder/info Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: folders:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "folderPath": "example", "bucket": "example", "scope": "org" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderPath": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Folder Info Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/folder/info without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### files.move Call POST /api/files/move. Contract: POST /api/files/move Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "fileKeys": [ "example" ], "targetFolder": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKeys": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "targetFolder": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "fileKeys", "targetFolder" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Files Move.", "additionalProperties": true } ``` Effects: May change state through POST /api/files/move. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### files.update Call PUT /api/file/update. Contract: PUT /api/file/update Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Files Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/file/update. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### files.content.update Call PUT /api/file-content. Contract: PUT /api/file-content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Files Content Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/file-content. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### download.signed_url.create Call POST /api/download/signed-url. Contract: POST /api/download/signed-url Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: files:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] }, "expirationMinutes": { "type": "number" }, "downloadFilename": { "type": "string" } }, "required": [ "key" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Download Signed Url Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/download/signed-url. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### video.mark_range_incompatible Call POST /api/video/mark-range-incompatible. Contract: POST /api/video/mark-range-incompatible Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: media:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "bucket": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "org", "private", "all" ] } }, "required": [ "key" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Video Mark Range Incompatible.", "additionalProperties": true } ``` Effects: May change state through POST /api/video/mark-range-incompatible. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Delete a non-default empty Bytes storage workspace. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.data.export Export a portable inventory of files and redacted share-link metadata for a Bytes workspace. Contract: GET /api/workspaces/{workspaceId}/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: storage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceId}/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.data.erase Permanently erase files, semantic vectors, and share links owned by a Bytes workspace. Contract: DELETE /api/workspaces/{workspaceId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Calendar source contract Human reference: https://docs.topolo.app/systems/topolo-calendar Machine reference: https://docs.topolo.app/machine/systems/topolo-calendar.json Source revisions: apps/TopoloCalendar@9e1b270431375af5b343e06176b64696084f5baf Deploy targets: 2; implemented actions: 32; declared actions: 32; uncatalogued served routes: 0; mobile contracts: 1; route signals: 22. ### privacy.export Export portable Calendar-owned data for the authenticated organization. Contract: GET /api/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Export organization Calendar data response", "description": "Operation result returned by privacy.export.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads privacy data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission privacy:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### privacy.erase Permanently erase Calendar-owned rows and avatar objects for the authenticated organization. Contract: DELETE /api/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Erase organization Calendar data response", "description": "Operation result returned by privacy.erase.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Permanently removes or invalidates privacy state. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission privacy:delete and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### privacy.protection.canary Verify every protected Calendar field is encrypted and readable under the active key ring. Contract: GET /api/privacy/protection/canary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "title": "Verify Calendar data protection response", "description": "Resource response returned by privacy.protection.canary. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true }, "privacy": { "type": "object", "title": "privacy record", "properties": { "id": { "type": "string", "description": "Stable identifier when the privacy exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads privacy data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission privacy:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### workspaces.delete Delete an empty, non-default Calendar workspace. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Delete workspace response", "description": "Operation result returned by workspaces.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "workspace record", "properties": { "id": { "type": "string", "description": "Stable identifier when the workspace exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Permanently removes or invalidates workspace state. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:delete and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### widget.get Get the Calendar widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: host:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "title": "Get widget summary response", "description": "Resource response returned by widget.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "widget record", "properties": { "id": { "type": "string", "description": "Stable identifier when the widget exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "widget record", "properties": { "id": { "type": "string", "description": "Stable identifier when the widget exposes one." } }, "additionalProperties": true }, "widget": { "type": "object", "title": "widget record", "properties": { "id": { "type": "string", "description": "Stable identifier when the widget exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads widget data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission host:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### host.get Get the selected workspace host profile. A new workspace returns host: null; call host.update once to create its first host before using availability, event types, bookings, or external calendars. Contract: GET /api/admin/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: host:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "title": "Get host profile response", "description": "Resource response returned by host.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, "host": { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads the selected workspace host profile. A new workspace returns host: null until host.update creates its first host. Verification: If host is null, call app_topolo_calendar.host.update before availability, event-type, booking, or external-calendar actions. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission host:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### host.update Create the first host for a new Calendar workspace or update its existing host profile. Calendar generates and preserves the public handle; callers do not provide one. Contract: PUT /api/admin/host Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: host:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "displayName": "Northstar Workshops", "timezone": "Asia/Makassar", "avatarUrl": null, "headline": "Hands-on coffee brewing workshops for adventurous teams.", "bio": "Northstar Coffee Roasters hosts practical TrailReady brewing sessions in Bali." } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "avatarUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "displayName", "timezone" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Create or update host profile response", "description": "Operation result returned by host.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Creates the first host for a new Calendar workspace, or updates the existing host profile. Calendar generates and preserves the public handle; callers do not supply one. Verification: Call app_topolo_calendar.host.get and confirm the returned display name, timezone, profile copy, and generated handle. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission host:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### event_types.list List calendar event types. Contract: GET /api/admin/event-types Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: event_types:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "title": "List event types response", "description": "Collection response returned by event_types.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, "event": { "type": "array", "items": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads event data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission event_types:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### event_types.create Create a calendar event type. Contract: POST /api/admin/event-types Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: event_types:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "slug": "example", "name": "example", "durationMinutes": 5 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "minNoticeMinutes": { "type": "integer", "minimum": 0, "maximum": 525600 }, "maxAdvanceDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "slotIncrementMinutes": { "type": "integer", "minimum": 5, "maximum": 240 }, "locationKind": { "type": "string", "enum": [ "chat_meeting", "microsoft_teams", "google_meet", "zoom", "in_person", "phone", "custom" ] }, "locationDetail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "slug", "name", "durationMinutes" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Create event type response", "description": "Operation result returned by event_types.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes event state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission event_types:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### bookings.list List calendar bookings. Contract: GET /api/admin/bookings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "windowStart": "2026-08-20T00:00:00+08:00", "windowEnd": "2026-08-21T00:00:00+08:00" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "windowStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "windowStart", "windowEnd" ], "additionalProperties": false } ``` Output schema: ```json { "title": "List bookings response", "description": "Collection response returned by bookings.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, "bookings": { "type": "array", "items": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads booking data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### bookings.create Create a calendar booking. Contract: POST /api/admin/bookings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "eventTypeId": "evt_northstar_wholesale_tasting", "startAt": "2026-08-20T10:00:00+08:00", "inviteeName": "Maya Chen", "inviteeEmail": "maya.chen@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "inviteeName": { "type": "string", "minLength": 1 }, "inviteeEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "eventTypeId": { "type": "string", "minLength": 1 }, "eventTypeSlug": { "type": "string", "minLength": 1 }, "recurrence": { "anyOf": [ { "type": "object", "properties": { "frequency": { "type": "string" }, "interval": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "count": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "until": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] } }, "required": [ "frequency", "interval" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "startAt", "inviteeName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Create booking response", "description": "Operation result returned by bookings.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes booking state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### bookings.update Update one calendar booking. Contract: PUT /api/admin/bookings/{bookingId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "bookingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "inviteeName": { "type": "string" }, "inviteeEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "bookingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Update booking response", "description": "Operation result returned by bookings.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes booking state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### bookings.cancel Cancel one calendar booking. Contract: POST /api/admin/bookings/{bookingId}/cancel Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "bookingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "bookingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Cancel booking response", "description": "Operation result returned by bookings.cancel.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Permanently removes or invalidates booking state. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### availability.get Get availability rules and overrides for the selected workspace host. If host.get returns host: null, create the host with host.update first. Contract: GET /api/admin/availability Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "title": "Get availability response", "description": "Resource response returned by availability.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, "availability": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads weekly availability and date overrides for the selected workspace host. Verification: Confirm the response belongs to the host returned by app_topolo_calendar.host.get. If that action returns host: null, create it with app_topolo_calendar.host.update first. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### availability.update Update availability rules. Contract: PUT /api/admin/availability Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "rules": [] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "rules": { "type": "array", "items": { "type": "object", "properties": { "dayOfWeek": { "type": "integer", "minimum": 0, "maximum": 6 }, "startMinute": { "type": "integer", "minimum": 0, "maximum": 1439 }, "endMinute": { "type": "integer", "minimum": 1, "maximum": 1440 } }, "required": [ "dayOfWeek", "startMinute", "endMinute" ], "additionalProperties": false } } }, "required": [ "rules" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Update availability response", "description": "Operation result returned by availability.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes availability state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### external_calendars.list List connected external calendars. Contract: GET /api/admin/external-calendars Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "title": "List external calendars response", "description": "Collection response returned by external_calendars.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, "external": { "type": "array", "items": { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads external data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### external_calendars.sync Sync an external calendar connection. Contract: POST /api/admin/external-calendars/{calendarId}/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "calendarId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "calendarId": { "type": "string", "minLength": 1 }, "blocks": { "type": "array", "items": { "type": "object", "properties": { "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "sourceUid": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "summary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "busyType": { "type": "string", "enum": [ "busy", "tentative", "out_of_office", "unknown" ] } }, "required": [ "startAt", "endAt" ], "additionalProperties": false } }, "nextSyncCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowStart": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "windowEnd": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" } }, "required": [ "calendarId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Sync external calendar response", "description": "Operation result returned by external_calendars.sync.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes external state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### host.avatar.upload Upload the authenticated host's avatar. Contract: POST /api/admin/host/avatar Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: host:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contentBase64": "Sample content base64", "contentType": "image/jpeg", "fileName": "Sample file name" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "enum": [ "image/jpeg", "image/png", "image/webp", "image/gif" ] }, "fileName": { "type": "string", "minLength": 1 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Upload host avatar response", "description": "Operation result returned by host.avatar.upload.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "host record", "properties": { "id": { "type": "string", "description": "Stable identifier when the host exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes host state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission host:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### event_types.get Get a Calendar event type. Contract: GET /api/admin/event-types/{eventTypeId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: event_types:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "eventTypeId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventTypeId": { "type": "string", "minLength": 1 } }, "required": [ "eventTypeId" ], "additionalProperties": false } ``` Output schema: ```json { "title": "Get event type response", "description": "Resource response returned by event_types.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, "event": { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads event data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission event_types:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### event_types.update Update a Calendar event type. Contract: PUT /api/admin/event-types/{eventTypeId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: event_types:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "eventTypeId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventTypeId": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "bufferBeforeMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "bufferAfterMinutes": { "type": "integer", "minimum": 0, "maximum": 1440 }, "minNoticeMinutes": { "type": "integer", "minimum": 0, "maximum": 525600 }, "maxAdvanceDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "slotIncrementMinutes": { "type": "integer", "minimum": 5, "maximum": 240 }, "locationKind": { "type": "string", "enum": [ "chat_meeting", "microsoft_teams", "google_meet", "zoom", "in_person", "phone", "custom" ] }, "locationDetail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayOrder": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "isActive": { "type": "boolean" }, "approvalRequired": { "type": "boolean" } }, "required": [ "eventTypeId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Update event type response", "description": "Operation result returned by event_types.update.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes event state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission event_types:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### event_types.delete Delete an unused Calendar event type. Contract: DELETE /api/admin/event-types/{eventTypeId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: event_types:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "eventTypeId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventTypeId": { "type": "string", "minLength": 1 } }, "required": [ "eventTypeId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Delete event type response", "description": "Operation result returned by event_types.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "event record", "properties": { "id": { "type": "string", "description": "Stable identifier when the event exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Permanently removes or invalidates event state. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission event_types:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### availability.overrides.list List host date-specific availability overrides. Contract: GET /api/admin/availability/overrides Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "title": "List availability overrides response", "description": "Collection response returned by availability.overrides.list. The service may return the collection directly or in an envelope.", "oneOf": [ { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, { "type": "object", "properties": { "data": { "oneOf": [ { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "items": { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, "availability": { "type": "array", "items": { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true } }, "count": { "type": "integer", "minimum": 0 }, "nextCursor": { "type": [ "string", "null" ] } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads availability data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### availability.overrides.create Create or replace a host date-specific availability override. Contract: POST /api/admin/availability/overrides Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "date": "2026-08-20", "startMinute": null, "endMinute": null } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string" }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "startMinute": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 1439 }, { "type": "null" } ] }, "endMinute": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1440 }, { "type": "null" } ] } }, "required": [ "date" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Create availability override response", "description": "Operation result returned by availability.overrides.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes availability state in the selected Topolo resource context. Verification: Call app_topolo_calendar.availability.overrides.list and confirm the returned date and minute bounds. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### availability.overrides.delete Delete a host date-specific availability override. Contract: DELETE /api/admin/availability/overrides/{overrideId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "overrideId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "overrideId": { "type": "string", "minLength": 1 } }, "required": [ "overrideId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Delete availability override response", "description": "Operation result returned by availability.overrides.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "availability record", "properties": { "id": { "type": "string", "description": "Stable identifier when the availability exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Permanently removes or invalidates availability state. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### bookings.get Get a Calendar booking and delivery details. Contract: GET /api/admin/bookings/{bookingId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "bookingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 } }, "required": [ "bookingId" ], "additionalProperties": false } ``` Output schema: ```json { "title": "Get booking response", "description": "Resource response returned by bookings.get. The service may return the resource directly or in an envelope.", "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "properties": { "data": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, "booking": { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true } }, "additionalProperties": true } ], "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Reads booking data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected resource context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:read and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### bookings.approve Approve a pending Calendar booking. Contract: POST /api/admin/bookings/{bookingId}/approve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "bookingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 } }, "required": [ "bookingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Approve booking response", "description": "Operation result returned by bookings.approve.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes booking state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### bookings.reschedule Reschedule a Calendar booking. Contract: POST /api/admin/bookings/{bookingId}/reschedule Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "bookingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 }, "startAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "endAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "durationMinutes": { "type": "integer", "minimum": 5, "maximum": 480 }, "inviteeName": { "type": "string" }, "inviteeEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeTimezone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "inviteeNotes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "bookingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Reschedule booking response", "description": "Operation result returned by bookings.reschedule.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes booking state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### bookings.invite.resend Resend the current booking invitation or cancellation notice. Contract: POST /api/admin/bookings/{bookingId}/resend-invite Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bookings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "bookingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "bookingId": { "type": "string", "minLength": 1 } }, "required": [ "bookingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Resend booking invite response", "description": "Operation result returned by bookings.invite.resend.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "booking record", "properties": { "id": { "type": "string", "description": "Stable identifier when the booking exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes booking state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission bookings:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### external_calendars.create Connect an ICS or manually synchronized external calendar. Contract: POST /api/admin/external-calendars Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "accountEmail": "agent@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "provider": { "type": "string", "enum": [ "ics", "manual" ] }, "accountEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "accountEmail" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Create external calendar response", "description": "Operation result returned by external_calendars.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes external state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### external_calendars.caldav.create Connect a CalDAV external calendar. Contract: POST /api/admin/external-calendars/caldav Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "accountEmail": "agent@example.com", "calendarUrl": "https://example.com", "username": "example", "password": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "accountEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "displayName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "calendarUrl": { "type": "string", "format": "uri" }, "username": { "type": "string", "minLength": 1 }, "password": { "type": "string", "minLength": 1 } }, "required": [ "accountEmail", "calendarUrl", "username", "password" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Connect CalDAV calendar response", "description": "Operation result returned by external_calendars.caldav.create.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes external state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### external_calendars.oauth.start Start an interactive Google or Microsoft calendar connection. Contract: POST /api/admin/external-calendars/oauth/start Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "provider": "google" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "provider": { "type": "string", "enum": [ "google", "microsoft" ] }, "redirectPath": { "type": "string" } }, "required": [ "provider" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Start calendar OAuth response", "description": "Operation result returned by external_calendars.oauth.start.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Changes external state in the selected Topolo resource context. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ### external_calendars.delete Disconnect an external calendar. Contract: DELETE /api/admin/external-calendars/{calendarId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: availability:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "calendarId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "calendarId": { "type": "string", "minLength": 1 } }, "required": [ "calendarId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "title": "Delete external calendar response", "description": "Operation result returned by external_calendars.delete.", "properties": { "success": { "type": "boolean" }, "id": { "type": "string" }, "data": { "oneOf": [ { "type": "object", "title": "external record", "properties": { "id": { "type": "string", "description": "Stable identifier when the external exposes one." } }, "additionalProperties": true }, { "type": "object", "additionalProperties": true } ] }, "result": { "type": "object", "additionalProperties": true }, "message": { "type": "string" } }, "additionalProperties": true, "x-topolo-contract-source": "derived-action-metadata", "x-topolo-contract-precision": "structural" } ``` Effects: Permanently removes or invalidates external state. Verification: Validate the response against outputSchema and re-read the affected resource to confirm the intended state. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission availability:write and the required resource binding. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. 409 state_conflict: Read the current resource state, reconcile the intended change, and retry only if still valid. ## Chat source contract Human reference: https://docs.topolo.app/systems/topolo-chat Machine reference: https://docs.topolo.app/machine/systems/topolo-chat.json Source revisions: apps/TopoloChat@9b3181a11595534171029d26d81de7134dcc4b9b Deploy targets: 2; implemented actions: 100; declared actions: 101; uncatalogued served routes: 0; mobile contracts: 1; route signals: 19. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### widget_chat.bootstrap Get contacts, recent conversations, unread totals, and realtime metadata for the cross-app Chat widget. Contract: GET /api/widget/chat Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget/chat without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### widget_chat.update_workspace_attention Set the current user attention level and optional snooze time for one resolved Chat workspace. Contract: PATCH /api/widget/workspaces/{workspaceId}/attention Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "attentionLevel": "all" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "attentionLevel": { "type": "string", "enum": [ "all", "mentions", "none" ] }, "snoozedUntil": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "workspaceId", "attentionLevel" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/widget/workspaces/{workspaceId}/attention. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.open_dm Create or open a human direct message conversation for the cross-app Chat widget. Contract: POST /api/widget/dms Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "memberId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "memberId": { "type": "string" }, "type": { "type": "string", "const": "human" } }, "required": [ "memberId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/dms. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.list_messages List normalized human direct-message messages for the cross-app Chat widget. Contract: GET /api/widget/dms/{conversationId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List cross-app Chat messages.", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget/dms/{conversationId}/messages without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### widget_chat.list_channel_messages List normalized channel messages for the cross-app Chat widget. Contract: GET /api/widget/channels/{channelId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List cross-app Chat channel messages.", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget/channels/{channelId}/messages without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### widget_chat.send_dm_message Send a human direct-message turn from the cross-app Chat widget. Contract: POST /api/widget/dms/{conversationId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Send cross-app Chat direct message.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/dms/{conversationId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.send_channel_message Send a channel message turn from the cross-app Chat widget. Contract: POST /api/widget/channels/{channelId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Send cross-app Chat channel message.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/channels/{channelId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.request_upload Create a compact upload draft for an image, file, or voice note sent from the cross-app Chat widget. Contract: POST /api/widget/uploads/request Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "fileName": "example", "contentType": "example", "sizeBytes": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "integer", "minimum": 1, "maximum": 26214400 } }, "required": [ "fileName", "contentType", "sizeBytes" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/uploads/request. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.upload_content Upload bytes for a compact widget upload draft. Contract: PUT /api/widget/uploads/{uploadId}/content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "uploadId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1 } }, "required": [ "uploadId" ], "additionalProperties": {} } ``` Output schema: ```json { "type": "object", "description": "Response returned by Upload cross-app Chat file content.", "additionalProperties": true } ``` Effects: May change state through PUT /api/widget/uploads/{uploadId}/content. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.complete_upload Attach an uploaded image, file, or voice note to a human direct message from the cross-app Chat widget. Contract: POST /api/widget/dms/{conversationId}/uploads/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "uploadIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "messageBody": { "type": "string" }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete cross-app Chat upload.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/dms/{conversationId}/uploads/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.complete_channel_upload Attach an uploaded image, file, or voice note to a channel message from the cross-app Chat widget. Contract: POST /api/widget/channels/{channelId}/uploads/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "uploadId": { "type": "string", "minLength": 1 }, "uploadIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "messageBody": { "type": "string" }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete cross-app Chat channel upload.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/channels/{channelId}/uploads/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.start_call Start a voice or video call for a human direct-message conversation from the cross-app Chat widget. Contract: POST /api/widget/dms/{conversationId}/calls Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "mode": { "type": "string", "enum": [ "audio", "video" ] } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Start cross-app Chat call.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/dms/{conversationId}/calls. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.mark_read Mark a cross-app Chat human direct-message conversation read. Contract: POST /api/widget/dms/{conversationId}/read Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Mark cross-app Chat conversation read.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/dms/{conversationId}/read. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_chat.mark_channel_read Mark a cross-app Chat channel conversation read. Contract: POST /api/widget/channels/{channelId}/read Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Mark cross-app Chat channel read.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/channels/{channelId}/read. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace.bootstrap Get the signed workspace bootstrap payload for this service. Contract: GET /api/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/bootstrap without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.export Export the verified workspace's Chat records and protected object inventory. Contract: GET /api/privacy/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/privacy/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.protection_canary Inspect the verified workspace for remaining unprotected Chat fields and objects. Platform super administrators may name a legacy workspace directly. Contract: GET /api/privacy/protection/canary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "targetWorkspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "targetWorkspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/privacy/protection/canary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.erase Permanently erase all Chat database rows and protected objects for the verified workspace. Contract: DELETE /api/privacy/workspace Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/privacy/workspace. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Delete an empty non-default Topolo Chat workspace. Contract: DELETE /api/chat/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/chat/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channels.list List workspace channels. Contract: GET /api/channels Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: channels:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List channels.", "additionalProperties": true } ``` Effects: Reads state through GET /api/channels without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### channels.create Create a workspace channel. Contract: POST /api/channels Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: channels:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "topic": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "topic": { "type": "string", "minLength": 1 }, "isPrivate": { "type": "boolean" }, "memberIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "name", "topic" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/channels. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.list List messages in a channel. Contract: GET /api/channels/{channelId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List channel messages.", "additionalProperties": true } ``` Effects: Reads state through GET /api/channels/{channelId}/messages without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### channel_messages.send Send a message to a channel. Contract: POST /api/channels/{channelId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Send channel message.", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.list List direct-message conversations. Contract: GET /api/dms Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List direct messages.", "additionalProperties": true } ``` Effects: Reads state through GET /api/dms without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### direct_messages.create Create a direct-message conversation. Contract: POST /api/dms Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "memberId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "memberId": { "type": "string", "minLength": 1 } }, "required": [ "memberId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create direct message.", "additionalProperties": true } ``` Effects: May change state through POST /api/dms. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.list List meetings. Contract: GET /api/meetings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List meetings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/meetings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### meetings.create Create a meeting. Contract: POST /api/meetings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "description": "example", "sourceKind": "channel", "sourceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "channel", "dm", "workspace" ] }, "sourceId": { "type": "string", "minLength": 1 }, "startsAt": { "type": "string" }, "durationMinutes": { "type": "number" }, "reminderMinutes": { "type": "number" }, "recurrenceRule": { "type": "string", "enum": [ "none", "daily", "weekdays", "weekly" ] }, "startNow": { "type": "boolean" } }, "required": [ "title", "description", "sourceKind", "sourceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create meeting.", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.end End a meeting. Contract: POST /api/meetings/{meetingId}/end Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by End meeting.", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/end. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### search.query Search channels, messages, and meetings. Contract: GET /api/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: search:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example", "scope": "messages", "conversationKind": "channel" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "scope": { "type": "string", "enum": [ "messages", "files", "people", "channels" ] }, "conversationKind": { "type": "string", "enum": [ "channel", "dm" ] }, "conversationId": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Search chat.", "additionalProperties": true } ``` Effects: Reads state through GET /api/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### uploads.request Request a chat upload slot. Contract: POST /api/uploads/request Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: uploads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "fileName": "example", "contentType": "example", "sizeBytes": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "sizeBytes": { "type": "number", "exclusiveMinimum": 0, "maximum": 26214400 } }, "required": [ "fileName", "contentType", "sizeBytes" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Request upload.", "additionalProperties": true } ``` Effects: May change state through POST /api/uploads/request. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### agent_personas.list List the workspace's TopoloAgent AI personas available to surface in Chat. Proxies to the Topolo Agent persona host. Contract: GET /api/agent-personas Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/agent-personas without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### agent_personas.send_message Send a message to a TopoloAgent persona on behalf of the acting user and receive the persona reply. Proxies to the Topolo Agent dual-identity session invoke surface. Contract: POST /api/agent-personas/{personaId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "personaId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "personaId": { "type": "string", "minLength": 1 }, "message": { "type": "string" }, "threadId": { "type": "string" }, "type": { "type": "string", "enum": [ "message", "approve" ] }, "approvalId": { "type": "string" }, "decision": { "type": "string" } }, "required": [ "personaId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/agent-personas/{personaId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### presence.get Execute Presence Get in Topolo Chat. Contract: GET /api/widget/presence Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget/presence without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### presence.update Execute Presence Update in Topolo Chat. Contract: POST /api/widget/presence Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "status": "available" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "enum": [ "available", "busy", "do_not_disturb", "be_right_back", "away", "offline" ] } }, "required": [ "status" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/presence. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### calls.join Execute Calls Join in Topolo Chat. Contract: POST /api/widget/dms/{conversationId}/calls/{callId}/join Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "callId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "callId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "callId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/dms/{conversationId}/calls/{callId}/join. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### calls.end Execute Calls End in Topolo Chat. Contract: POST /api/widget/dms/{conversationId}/calls/{callId}/end Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "conversationId": "example", "callId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "callId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "enum": [ "no_answer", "missed", "declined" ] }, "mode": { "type": "string", "enum": [ "audio", "video" ] } }, "required": [ "conversationId", "callId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/widget/dms/{conversationId}/calls/{callId}/end. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channels.update Execute Channels Update in Topolo Chat. Contract: POST /api/channels/{channelId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: channels:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "topic": { "type": "string", "minLength": 1 }, "isPrivate": { "type": "boolean" } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channels.archive Execute Channels Archive in Topolo Chat. Contract: POST /api/channels/{channelId}/archive Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: channels:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/archive. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channels.delete Execute Channels Delete in Topolo Chat. Contract: DELETE /api/channels/{channelId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: channels:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/channels/{channelId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.thread Execute Channel Messages Thread in Topolo Chat. Contract: GET /api/channels/{channelId}/messages/{messageId}/thread Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "channelId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/channels/{channelId}/messages/{messageId}/thread without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### channel_messages.forward Execute Channel Messages Forward in Topolo Chat. Contract: POST /api/channels/{channelId}/messages/forward Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "sourceKind": "channel", "sourceConversationId": "example", "sourceMessageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "channel", "dm" ] }, "sourceConversationId": { "type": "string", "minLength": 1 }, "sourceMessageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "sourceKind", "sourceConversationId", "sourceMessageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages/forward. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.save Execute Channel Messages Save in Topolo Chat. Contract: POST /api/channels/{channelId}/messages/{messageId}/save Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages/{messageId}/save. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.update Execute Channel Messages Update in Topolo Chat. Contract: POST /api/channels/{channelId}/messages/{messageId}/update Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "messageId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages/{messageId}/update. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.delete Execute Channel Messages Delete in Topolo Chat. Contract: POST /api/channels/{channelId}/messages/{messageId}/delete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "channelId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages/{messageId}/delete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.react Execute Channel Messages React in Topolo Chat. Contract: POST /api/channels/{channelId}/messages/{messageId}/reactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "messageId": "example", "emoji": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "emoji": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId", "emoji" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages/{messageId}/reactions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.pin Execute Channel Messages Pin in Topolo Chat. Contract: POST /api/channels/{channelId}/messages/{messageId}/pin Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages/{messageId}/pin. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channel_messages.mark_unread Execute Channel Messages Mark Unread in Topolo Chat. Contract: POST /api/channels/{channelId}/messages/{messageId}/unread Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "channelId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/messages/{messageId}/unread. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channels.mark_read Execute Channels Mark Read in Topolo Chat. Contract: POST /api/channels/{channelId}/read Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 } }, "required": [ "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/read. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### channels.mute Execute Channels Mute in Topolo Chat. Contract: POST /api/channels/{channelId}/mute Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "channelId": "example", "muted": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channelId": { "type": "string", "minLength": 1 }, "muted": { "type": "boolean" } }, "required": [ "channelId", "muted" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/channels/{channelId}/mute. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.manage Execute Direct Messages Manage in Topolo Chat. Contract: GET /api/dms/manage Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/dms/manage without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### direct_messages.messages Execute Direct Messages Messages in Topolo Chat. Contract: GET /api/dms/{conversationId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500 }, "before": { "type": "string" } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/dms/{conversationId}/messages without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### direct_messages.thread Execute Direct Messages Thread in Topolo Chat. Contract: GET /api/dms/{conversationId}/messages/{messageId}/thread Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "conversationId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/dms/{conversationId}/messages/{messageId}/thread without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### direct_messages.forward Execute Direct Messages Forward in Topolo Chat. Contract: POST /api/dms/{conversationId}/messages/forward Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "sourceKind": "channel", "sourceConversationId": "example", "sourceMessageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "sourceKind": { "type": "string", "enum": [ "channel", "dm" ] }, "sourceConversationId": { "type": "string", "minLength": 1 }, "sourceMessageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "sourceKind", "sourceConversationId", "sourceMessageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/messages/forward. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.save Execute Direct Messages Save in Topolo Chat. Contract: POST /api/dms/{conversationId}/messages/{messageId}/save Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/messages/{messageId}/save. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.send Execute Direct Messages Send in Topolo Chat. Contract: POST /api/dms/{conversationId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "threadParentId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.update Execute Direct Messages Update in Topolo Chat. Contract: POST /api/dms/{conversationId}/messages/{messageId}/update Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "messageId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/messages/{messageId}/update. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.delete Execute Direct Messages Delete in Topolo Chat. Contract: POST /api/dms/{conversationId}/messages/{messageId}/delete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "conversationId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/messages/{messageId}/delete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.react Execute Direct Messages React in Topolo Chat. Contract: POST /api/dms/{conversationId}/messages/{messageId}/reactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "messageId": "example", "emoji": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "emoji": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId", "emoji" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/messages/{messageId}/reactions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.mark_unread Execute Direct Messages Mark Unread in Topolo Chat. Contract: POST /api/dms/{conversationId}/messages/{messageId}/unread Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "messageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId", "messageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/messages/{messageId}/unread. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.mark_read Execute Direct Messages Mark Read in Topolo Chat. Contract: POST /api/dms/{conversationId}/read Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/read. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.mute Execute Direct Messages Mute in Topolo Chat. Contract: POST /api/dms/{conversationId}/mute Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "muted": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "muted": { "type": "boolean" } }, "required": [ "conversationId", "muted" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/mute. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### direct_messages.archive Execute Direct Messages Archive in Topolo Chat. Contract: POST /api/dms/{conversationId}/archive Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: direct_messages:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example", "archived": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "archived": { "type": "boolean" } }, "required": [ "conversationId", "archived" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/dms/{conversationId}/archive. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### audit_events.list Execute Audit Events List in Topolo Chat. Contract: GET /api/audit-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/audit-events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### files.download Execute Files Download in Topolo Chat. Contract: GET /api/files/{fileKey} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "fileKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fileKey": { "type": "string", "minLength": 1 } }, "required": [ "fileKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/files/{fileKey} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### meetings.get Execute Meetings Get in Topolo Chat. Contract: GET /api/meetings/{meetingId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/meetings/{meetingId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### meeting_messages.list Execute Meeting Messages List in Topolo Chat. Contract: GET /api/meetings/{meetingId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/meetings/{meetingId}/messages without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### meeting_messages.send Execute Meeting Messages Send in Topolo Chat. Contract: POST /api/meetings/{meetingId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meeting_messages.react Execute Meeting Messages React in Topolo Chat. Contract: POST /api/meetings/{meetingId}/messages/{messageId}/reactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "messageId": "example", "emoji": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "messageId": { "type": "string", "minLength": 1 }, "emoji": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "messageId", "emoji" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/messages/{messageId}/reactions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meeting_polls.list Execute Meeting Polls List in Topolo Chat. Contract: GET /api/meetings/{meetingId}/polls Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/meetings/{meetingId}/polls without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### meeting_polls.create Execute Meeting Polls Create in Topolo Chat. Contract: POST /api/meetings/{meetingId}/polls Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "question": "example", "options": [ "example", "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "question": { "type": "string", "minLength": 1 }, "options": { "minItems": 2, "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "meetingId", "question", "options" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/polls. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meeting_polls.vote Execute Meeting Polls Vote in Topolo Chat. Contract: POST /api/meetings/{meetingId}/polls/{pollId}/vote Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "pollId": "example", "optionIndex": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "pollId": { "type": "string", "minLength": 1 }, "optionIndex": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "meetingId", "pollId", "optionIndex" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/polls/{pollId}/vote. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meeting_notes.create Execute Meeting Notes Create in Topolo Chat. Contract: POST /api/meetings/{meetingId}/notes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/notes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.calendar Execute Meetings Calendar in Topolo Chat. Contract: GET /api/meetings/{meetingId}/calendar Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/meetings/{meetingId}/calendar without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### meetings.update Execute Meetings Update in Topolo Chat. Contract: POST /api/meetings/{meetingId}/update Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "startsAt": { "type": "string" }, "durationMinutes": { "type": "number", "exclusiveMinimum": 0 }, "reminderMinutes": { "type": "number", "minimum": 0 }, "recurrenceRule": { "type": "string", "enum": [ "none", "daily", "weekdays", "weekly" ] }, "status": { "type": "string", "enum": [ "live", "scheduled", "completed", "cancelled" ] } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/update. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.delete Execute Meetings Delete in Topolo Chat. Contract: DELETE /api/meetings/{meetingId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/meetings/{meetingId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.guest_invite Execute Meetings Guest Invite in Topolo Chat. Contract: POST /api/meetings/{meetingId}/guest-invites Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "email": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "meetingId", "email" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/guest-invites. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.transcript Execute Meetings Transcript in Topolo Chat. Contract: GET /api/meetings/{meetingId}/transcript Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/meetings/{meetingId}/transcript without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### meetings.join_token Execute Meetings Join Token in Topolo Chat. Contract: POST /api/meetings/{meetingId}/join-token Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/join-token. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.admit Execute Meetings Admit in Topolo Chat. Contract: POST /api/meetings/{meetingId}/admit Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "participantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "participantId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "participantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/admit. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.remove_participant Execute Meetings Remove Participant in Topolo Chat. Contract: POST /api/meetings/{meetingId}/remove-participant Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "meetingId": "example", "participantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "participantId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "participantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/remove-participant. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.update_role Execute Meetings Update Role in Topolo Chat. Contract: POST /api/meetings/{meetingId}/update-role Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "participantId": "example", "role": "host" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "participantId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "host", "co_host", "presenter", "participant", "guest" ] } }, "required": [ "meetingId", "participantId", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/update-role. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.lock Execute Meetings Lock in Topolo Chat. Contract: POST /api/meetings/{meetingId}/lock Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "locked": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "locked": { "type": "boolean" } }, "required": [ "meetingId", "locked" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/lock. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.recording_start Execute Meetings Recording Start in Topolo Chat. Contract: POST /api/meetings/{meetingId}/recording/start Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/recording/start. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.recording_stop Execute Meetings Recording Stop in Topolo Chat. Contract: POST /api/meetings/{meetingId}/recording/stop Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/recording/stop. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### meetings.captions_toggle Execute Meetings Captions Toggle in Topolo Chat. Contract: POST /api/meetings/{meetingId}/captions/toggle Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "enabled": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" } }, "required": [ "meetingId", "enabled" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/captions/toggle. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### remote_assist.request Execute Remote Assist Request in Topolo Chat. Contract: POST /api/meetings/{meetingId}/remote-assist/request Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "hostName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "hostName": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "hostName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/remote-assist/request. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### remote_assist.approve Execute Remote Assist Approve in Topolo Chat. Contract: POST /api/meetings/{meetingId}/remote-assist/{sessionId}/approve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meetingId": "example", "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/remote-assist/{sessionId}/approve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### remote_assist.revoke Execute Remote Assist Revoke in Topolo Chat. Contract: POST /api/meetings/{meetingId}/remote-assist/{sessionId}/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "meetingId": "example", "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/meetings/{meetingId}/remote-assist/{sessionId}/revoke. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### remote_assist.state Execute Remote Assist State in Topolo Chat. Contract: GET /api/meetings/{meetingId}/remote-assist/{sessionId}/state Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: meetings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "meetingId": "example", "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "meetingId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "meetingId", "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/meetings/{meetingId}/remote-assist/{sessionId}/state without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### operational_threads.list Execute Operational Threads List in Topolo Chat. Contract: GET /api/operational-threads Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: operational_threads:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "view": "open", "state": "open", "updatedAfter": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "view": { "type": "string", "enum": [ "open", "recent" ] }, "state": { "type": "string", "enum": [ "open", "acknowledged", "snoozed", "resolved" ] }, "updatedAfter": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 }, "sourceSystem": { "type": "string" }, "externalRef": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/operational-threads without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### operational_threads.get Execute Operational Threads Get in Topolo Chat. Contract: GET /api/operational-threads/{threadId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: operational_threads:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "threadId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 } }, "required": [ "threadId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/operational-threads/{threadId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### operational_threads.create Execute Operational Threads Create in Topolo Chat. Contract: POST /api/operational-threads Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: operational_threads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "summary": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "severity": { "type": "string" }, "state": { "type": "string", "enum": [ "open", "acknowledged", "snoozed", "resolved" ] }, "sourceSystem": { "type": "string" }, "externalRef": { "type": "string" }, "ownerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snoozedUntil": { "type": "string" } }, "required": [ "title", "summary" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operational-threads. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operational_threads.update Execute Operational Threads Update in Topolo Chat. Contract: POST /api/operational-threads/{threadId}/update Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: operational_threads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "threadId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "summary": { "type": "string", "minLength": 1 }, "severity": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sourceSystem": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "externalRef": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "threadId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operational-threads/{threadId}/update. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operational_threads.transition Execute Operational Threads Transition in Topolo Chat. Contract: POST /api/operational-threads/{threadId}/state Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: operational_threads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "threadId": "example", "state": "open" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "open", "acknowledged", "snoozed", "resolved" ] }, "snoozedUntil": { "type": "string" } }, "required": [ "threadId", "state" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operational-threads/{threadId}/state. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operational_threads.assign_owner Execute Operational Threads Assign Owner in Topolo Chat. Contract: POST /api/operational-threads/{threadId}/owner Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: operational_threads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "threadId": "example", "ownerId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "ownerId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "threadId", "ownerId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operational-threads/{threadId}/owner. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operational_threads.comment Execute Operational Threads Comment in Topolo Chat. Contract: POST /api/operational-threads/{threadId}/comments Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: operational_threads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "threadId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "threadId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 } }, "required": [ "threadId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operational-threads/{threadId}/comments. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### notification_preferences.update Execute Notification Preferences Update in Topolo Chat. Contract: POST /api/notification-preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "directMessages": true, "channelMentions": true, "meetingReminders": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "directMessages": { "type": "boolean" }, "channelMentions": { "type": "boolean" }, "meetingReminders": { "type": "boolean" }, "recordingAlerts": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/notification-preferences. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace_policies.update Execute Workspace Policies Update in Topolo Chat. Contract: POST /api/workspace-policies Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "guestsEnabled": true, "waitingRoomDefault": true, "recordingEnabled": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "guestsEnabled": { "type": "boolean" }, "waitingRoomDefault": { "type": "boolean" }, "recordingEnabled": { "type": "boolean" }, "transcriptsEnabled": { "type": "boolean" }, "screenShareEnabled": { "type": "boolean" }, "remoteAssistEnabled": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/workspace-policies. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### uploads.content Execute Uploads Content in Topolo Chat. Contract: PUT /api/uploads/{uploadId}/content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: uploads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "uploadId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1 } }, "required": [ "uploadId" ], "additionalProperties": {} } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/uploads/{uploadId}/content. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### uploads.complete Execute Uploads Complete in Topolo Chat. Contract: POST /api/uploads/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: uploads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "uploadId": "example", "conversationKind": "channel", "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1 }, "conversationKind": { "type": "string", "enum": [ "channel", "dm" ] }, "conversationId": { "type": "string", "minLength": 1 }, "messageBody": { "type": "string" }, "threadParentId": { "type": "string", "minLength": 1 }, "thread_parent_id": { "type": "string", "minLength": 1 } }, "required": [ "uploadId", "conversationKind", "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/uploads/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Improve Topolo source contract Human reference: https://docs.topolo.app/systems/topolo-bugfix Machine reference: https://docs.topolo.app/machine/systems/topolo-bugfix.json Source revisions: system-apps/TopoloBugFix@f255bd2ae4f710130f36e8f5c6e42bd9fdac21f1, system-apps/TopoloBugFixRunner@92dcf622930a7b0c034d567f8362505b448294b5 Deploy targets: 2; implemented actions: 25; declared actions: 25; uncatalogued served routes: 0; mobile contracts: 0; route signals: 7. ### widget.get Get the TopoloOne widget summary for BugFix. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.export Export organization-authored BugFix data without credentials. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase organization-authored BugFix data after active work is stopped and literal ERASE confirmation is provided. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "example", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### reports.create Create an authenticated bug report for a Topolo application. Contract: POST /api/actions/reports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "description": "example", "appName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "appName": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "appVersion": { "type": "string" }, "pageUrl": { "type": "string" }, "userAgent": { "type": "string" }, "screenshot": { "type": "string" }, "consoleErrors": {}, "componentStack": { "type": "string" }, "additionalContext": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "title", "description", "appName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/actions/reports. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### reports.list List bug reports visible to the active principal. Contract: GET /api/reports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "app": "example", "status": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "app": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/reports without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### reports.get Get one bug report. Contract: GET /api/reports/{reportId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "reportId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/reports/{reportId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### reports.status.get Get the current status and related fixes for one bug report. Contract: GET /api/reports/{reportId}/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "reportId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/reports/{reportId}/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### reports.fix.generate Start AI fix generation for one bug report. Contract: POST /api/reports/{reportId}/fix Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runs:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "reportId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/reports/{reportId}/fix. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### fixes.get Get one generated fix and its pull-request state. Contract: GET /api/fixes/{fixId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "fixId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fixId": { "type": "string", "minLength": 1 } }, "required": [ "fixId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/fixes/{fixId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### fixes.approve Approve one generated fix and merge its open pull request. Contract: POST /api/fixes/{fixId}/approve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "fixId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fixId": { "type": "string", "minLength": 1 } }, "required": [ "fixId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/fixes/{fixId}/approve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### fixes.reject Reject one generated fix and close its open pull request. Contract: POST /api/fixes/{fixId}/reject Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "fixId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fixId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "fixId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/fixes/{fixId}/reject. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.stats.get Get platform BugFix operational statistics. Contract: GET /api/admin/stats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/stats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### queue.retry Move selected failed reports back to pending. Contract: POST /api/admin/retry Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "reportIds": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "reportIds" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/retry. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### queue.list List the platform BugFix review queue. Contract: GET /api/admin/queue Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "status": "example", "app": "example", "severity": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "app": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/queue without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### queue.stats.get Get review queue totals by state. Contract: GET /api/admin/queue/stats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/queue/stats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### queue.report.get Get one report from the platform review queue. Contract: GET /api/admin/queue/{reportId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "reportId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 } }, "required": [ "reportId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/queue/{reportId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### queue.report.update Update review notes, guidance, priority, target, assignment, or state. Contract: PUT /api/admin/queue/{reportId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "reportId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 }, "admin_notes": { "type": "string" }, "admin_guidance": { "type": "string" }, "priority": { "type": "string" }, "target_repo": { "type": "string" }, "target_branch": { "type": "string" }, "assigned_agent": { "type": "string" }, "status": { "type": "string" } }, "required": [ "reportId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/admin/queue/{reportId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### queue.report.generate Trigger AI fix generation for one queued report with optional guidance. Contract: POST /api/admin/queue/{reportId}/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runs:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "reportId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 }, "agent": { "type": "string" }, "additional_guidance": { "type": "string" } }, "required": [ "reportId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/queue/{reportId}/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### queue.report.dismiss Dismiss one queued report with an optional reason. Contract: POST /api/admin/queue/{reportId}/dismiss Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "reportId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "reportId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" } }, "required": [ "reportId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/queue/{reportId}/dismiss. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### settings.public.get Get BugReporter enablement and auto-fix status. Contract: GET /api/settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: issues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/settings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### auto_fix.get Get the current auto-fix kill-switch state and recent changes. Contract: GET /api/admin/auto-fix Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bugfix:admin Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/auto-fix without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### auto_fix.toggle Enable or disable the manual auto-fix switch. Contract: POST /api/admin/auto-fix/toggle Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bugfix:admin Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "enabled": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "enabled": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "enabled" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/auto-fix/toggle. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.settings.list List all platform BugFix settings. Contract: GET /api/admin/settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bugfix:admin Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/settings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.settings.update Update one platform BugFix setting. Contract: PUT /api/admin/settings/{key} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bugfix:admin Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "value": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "value": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] } }, "required": [ "key", "value" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/admin/settings/{key}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.settings.bulk_update Update multiple platform BugFix settings atomically from one request. Contract: POST /api/admin/settings/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: bugfix:admin Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "settings": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "number" } ] } } }, "required": [ "settings" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/settings/bulk. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Social Studio source contract Human reference: https://docs.topolo.app/systems/topolo-social-studio Machine reference: https://docs.topolo.app/machine/systems/topolo-social-studio.json Source revisions: apps/TopoloSocialStudio@e59a4cb80a4e7154108acb7133a5127016e6540c Deploy targets: 3; implemented actions: 47; declared actions: 47; uncatalogued served routes: 0; mobile contracts: 1; route signals: 11. ### organizations.data.export Export all Social Studio data and asset object metadata owned by the authenticated organization across four D1 stores without credentials. Contract: GET /api/organizations/data/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/data/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Permanently erase all Social Studio data and asset objects owned by the authenticated organization while retaining backups under policy. Contract: DELETE /api/organizations/data/erase Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Delete a non-default empty Social Studio workspace. Contract: DELETE /api/workspaces/{workspaceSlug} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceSlug}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.create Create a Social Studio project. Contract: POST /api/workspaces/{workspaceSlug}/projects Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "title": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "objective": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "templateId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brandKitId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "title" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create project.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.duplicate Duplicate a Social Studio project. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/duplicate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: briefs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "includeAssets": { "type": "boolean" } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Duplicate project.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/duplicate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### planning.generate Generate a project creative plan. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/planning/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: briefs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "freeformPrompt": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "freeformPrompt": { "type": "string", "minLength": 1, "maxLength": 20000 }, "title": { "type": "string", "maxLength": 255 }, "platforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } }, "durationMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 180000 }, "style": { "type": "string", "maxLength": 4000 }, "captions": { "type": "string", "enum": [ "auto", "manual", "none" ] }, "objective": { "type": "string", "maxLength": 4000 }, "audience": { "type": "string", "maxLength": 4000 } }, "required": [ "workspaceSlug", "projectId", "freeformPrompt" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate project plan.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/planning/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.approval_requests.create Request approval from an active Social Studio workspace member. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/approval-requests Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: approvals:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "reviewerUserId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "reviewerUserId": { "type": "string", "minLength": 1 }, "note": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "reviewerUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Persisted approval request.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/approval-requests. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### generation.start Start generation for a project. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/generation/start Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: generation:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "provider": { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, "fallbackProvider": { "anyOf": [ { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, { "type": "null" } ] }, "candidateCount": { "type": "integer", "minimum": 1, "maximum": 4 }, "sourceAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputKind": { "type": "string", "enum": [ "image", "video" ] }, "videoDurationSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 15 }, { "type": "null" } ] }, "nexusProviderOverride": { "anyOf": [ { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, { "type": "null" } ] }, "nexusModelOverride": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Start generation.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/generation/start. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operator.backup_export Get a complete owner-only Social Studio workspace export. Contract: GET /api/workspaces/{workspaceSlug}/operator/backup-export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get backup export.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/operator/backup-export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### billing.entitlements.check Call POST /api/workspaces/{workspaceSlug}/billing/entitlements/check. Contract: POST /api/workspaces/{workspaceSlug}/billing/entitlements/check Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "action": "project.create" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "action": { "type": "string", "enum": [ "project.create", "planning.generate", "generation.start", "generation.regenerate", "render.create", "billing.portal", "usage.reconcile", "brand_kits.use", "batch_variants.use" ] }, "requestedGenerationUnits": { "type": "number", "minimum": 0 }, "requestedRenderJobs": { "type": "number", "minimum": 0 }, "requestedStorageBytes": { "type": "number", "minimum": 0 }, "featureKey": { "type": "string", "enum": [ "batch_variants", "brand_kits", "priority_render", "billing_portal", "operator_reconciliation" ] } }, "required": [ "workspaceSlug", "action" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Entitlements Check.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/billing/entitlements/check. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.portal_session.create Call POST /api/workspaces/{workspaceSlug}/billing/portal-session. Contract: POST /api/workspaces/{workspaceSlug}/billing/portal-session Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Portal Session Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/billing/portal-session. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.reconciliations.create Call POST /api/workspaces/{workspaceSlug}/billing/reconciliations. Contract: POST /api/workspaces/{workspaceSlug}/billing/reconciliations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: approvals:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "metricKey": "generation_units", "quantityDelta": 1, "unit": "example", "reason": "example", "description": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "metricKey": { "type": "string", "enum": [ "generation_units", "storage_bytes", "render_jobs", "premium_batch_variants", "premium_brand_kits" ] }, "quantityDelta": { "type": "number" }, "unit": { "type": "string", "minLength": 1, "maxLength": 64 }, "reason": { "type": "string", "minLength": 1, "maxLength": 1000 }, "description": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "workspaceSlug", "metricKey", "quantityDelta", "unit", "reason", "description" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Reconciliations Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/billing/reconciliations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.subscription.update Call PATCH /api/workspaces/{workspaceSlug}/billing/subscription. Contract: PATCH /api/workspaces/{workspaceSlug}/billing/subscription Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "planKey": { "type": "string", "enum": [ "free", "trial", "pro", "agency" ] }, "status": { "type": "string", "enum": [ "trialing", "active", "grace_period", "past_due", "suspended", "cancelled" ] }, "supportPlanLabel": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "invoiceEmail": { "anyOf": [ { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, { "type": "null" } ] }, "providerCustomerId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "providerSubscriptionId": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Subscription Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/billing/subscription. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### telemetry.events.create Call POST /api/workspaces/{workspaceSlug}/telemetry/events. Contract: POST /api/workspaces/{workspaceSlug}/telemetry/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "stream": "product", "channel": "worker", "eventName": "app.opened", "status": "success", "severity": "info" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "stream": { "type": "string", "enum": [ "product", "operational", "security", "audit" ] }, "channel": { "type": "string", "enum": [ "worker", "queue", "desktop", "web" ] }, "eventName": { "type": "string", "enum": [ "app.opened", "auth.login.success", "auth.login.failure", "project.created", "project.duplicated", "project.deleted", "template.applied", "brief.generated", "creative_plan.generated", "scene.generated", "asset.generation.started", "asset.generation.succeeded", "asset.generation.failed", "caption.edited", "library.asset.saved", "library.asset.reused", "variants.generated", "render.preview.started", "render.preview.completed", "render.final_export.started", "render.final_export.completed", "billing.entitlement.denied", "billing.portal.opened", "billing.reconciliation.applied", "provider.retry.scheduled", "provider.normalization.failed", "provider.moderation.failed", "sync.failed", "rate_limit.triggered", "moderation.blocked", "security.audit.recorded" ] }, "status": { "type": "string", "enum": [ "success", "failure", "pending", "denied", "blocked", "review" ] }, "severity": { "type": "string", "enum": [ "info", "warning", "error", "critical" ] }, "correlationId": { "type": "string" }, "errorCode": { "anyOf": [ { "type": "string", "enum": [ "auth_failure", "billing_limit", "moderation_block", "provider_failure", "provider_retryable", "quota_failure", "rate_limit", "render_failure", "security_violation", "sync_failure", "unknown" ] }, { "type": "null" } ] }, "message": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "latencyMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "workspaceSlug", "stream", "channel", "eventName", "status", "severity" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Telemetry Events Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/telemetry/events. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### assets.access_token.create Call POST /api/workspaces/{workspaceSlug}/assets/{assetId}/access-token. Contract: POST /api/workspaces/{workspaceSlug}/assets/{assetId}/access-token Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "assetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "assetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assets Access Token Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/assets/{assetId}/access-token. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### assets.library.save Call POST /api/workspaces/{workspaceSlug}/assets/{assetId}/library. Contract: POST /api/workspaces/{workspaceSlug}/assets/{assetId}/library Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "assetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "tags": { "type": "array", "items": { "type": "string" } }, "favorite": { "type": "boolean" } }, "required": [ "workspaceSlug", "assetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assets Library Save.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/assets/{assetId}/library. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### library.assets.reuse Call POST /api/workspaces/{workspaceSlug}/library/assets/{entryId}/reuse. Contract: POST /api/workspaces/{workspaceSlug}/library/assets/{entryId}/reuse Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "entryId": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "entryId": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "entryId", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Library Assets Reuse.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/library/assets/{entryId}/reuse. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### project_templates.create Call POST /api/workspaces/{workspaceSlug}/project-templates. Contract: POST /api/workspaces/{workspaceSlug}/project-templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promptDefaults": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } } }, "required": [ "workspaceSlug", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Project Templates Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/project-templates. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### project_templates.update Call PATCH /api/workspaces/{workspaceSlug}/project-templates/{templateId}. Contract: PATCH /api/workspaces/{workspaceSlug}/project-templates/{templateId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "templateId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "promptDefaults": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "platforms": { "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } }, "workspaceSlug": { "type": "string", "minLength": 1 }, "templateId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "workspaceSlug", "templateId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Project Templates Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/project-templates/{templateId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### presets.create Call POST /api/workspaces/{workspaceSlug}/presets. Contract: POST /api/workspaces/{workspaceSlug}/presets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } }, "required": [ "workspaceSlug", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Presets Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/presets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### presets.update Call PATCH /api/workspaces/{workspaceSlug}/presets/{presetId}. Contract: PATCH /api/workspaces/{workspaceSlug}/presets/{presetId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "presetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } }, "workspaceSlug": { "type": "string", "minLength": 1 }, "presetId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "workspaceSlug", "presetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Presets Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/presets/{presetId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.compositions.create Call POST /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "title": "example", "aspectRatio": "portrait_9_16", "snapshot": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "aspectRatio": { "type": "string", "enum": [ "portrait_9_16", "landscape_16_9" ] }, "snapshot": {}, "notes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "sourceKind": { "type": "string", "enum": [ "manual", "ai_generated", "imported" ] }, "generationStatus": { "type": "string", "enum": [ "pending", "queued", "running", "completed", "failed", "cancelled" ] } }, "required": [ "workspaceSlug", "projectId", "title", "aspectRatio", "snapshot" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Compositions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.compositions.update Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions/{compositionVersionId}. Contract: PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions/{compositionVersionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "compositionVersionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "compositionVersionId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "maxLength": 255 }, "aspectRatio": { "type": "string", "enum": [ "portrait_9_16", "landscape_16_9" ] }, "snapshot": {}, "notes": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "generationStatus": { "type": "string", "enum": [ "pending", "queued", "running", "completed", "failed", "cancelled" ] } }, "required": [ "workspaceSlug", "projectId", "compositionVersionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Compositions Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/compositions/{compositionVersionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.render_jobs.create Call POST /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "compositionVersionId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 255 }, "outputFormat": { "type": "string", "enum": [ "mp4", "mov", "png_sequence", "gif" ] }, "priority": { "type": "integer", "minimum": 0, "maximum": 10 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Render Jobs Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.render_jobs.update Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs/{renderJobId}. Contract: PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs/{renderJobId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "renderJobId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "renderJobId": { "type": "string", "minLength": 1 }, "renderStatus": { "type": "string", "enum": [ "queued", "rendering", "completed", "failed", "cancelled" ] }, "failureReason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "renderJobId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Render Jobs Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/render-jobs/{renderJobId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.scenes.regenerate Call POST /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}/generation/regenerate. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}/generation/regenerate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: generation:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "sceneId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "provider": { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, "fallbackProvider": { "anyOf": [ { "type": "string", "enum": [ "nexus-configured", "grok-imagine", "nano-banana", "cloudflare-media" ] }, { "type": "null" } ] }, "candidateCount": { "type": "integer", "minimum": 1, "maximum": 4 }, "sourceAssetId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "outputKind": { "type": "string", "enum": [ "image", "video" ] }, "videoDurationSeconds": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 15 }, { "type": "null" } ] }, "nexusProviderOverride": { "anyOf": [ { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, { "type": "null" } ] }, "nexusModelOverride": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "sceneId": { "type": "string", "minLength": 1 }, "assetId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "sceneId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Scenes Regenerate.", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}/generation/regenerate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.structured_brief.update Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/structured-brief. Contract: PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/structured-brief Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: briefs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "maxLength": 255 }, "objective": { "type": "string", "maxLength": 4000 }, "audience": { "type": "string", "maxLength": 4000 }, "keyMessage": { "type": "string", "maxLength": 4000 }, "channels": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] } }, "deliverables": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "constraints": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "referenceUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "successMetric": { "type": "string", "maxLength": 1000 }, "tonePillars": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "sourcePrompt": { "type": "string", "maxLength": 20000 }, "preferredDurationMs": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 180000 }, { "type": "null" } ] }, "styleNotes": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "captionMode": { "type": "string", "enum": [ "auto", "manual", "none" ] } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Structured Brief Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/structured-brief. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.creative_plan.update Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/creative-plan. Contract: PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/creative-plan Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: briefs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "instagram", "tiktok", "youtube", "linkedin", "x", "facebook" ] }, "concept": { "type": "string", "maxLength": 4000 }, "hook": { "type": "string", "maxLength": 1000 }, "hookStrategy": { "type": "string", "maxLength": 4000 }, "callToAction": { "type": "string", "maxLength": 1000 }, "pacingStrategy": { "type": "string", "maxLength": 4000 }, "narrativeArc": { "type": "string", "maxLength": 4000 }, "narrativeStructure": { "type": "string", "maxLength": 4000 }, "visualDirection": { "type": "string", "maxLength": 4000 }, "shotStyle": { "type": "string", "maxLength": 4000 }, "providerStrategy": { "type": "object", "properties": { "imagePromptShape": { "type": "string", "minLength": 1, "maxLength": 4000 }, "motionPromptShape": { "type": "string", "minLength": 1, "maxLength": 4000 }, "renderTarget": { "type": "string", "minLength": 1, "maxLength": 4000 }, "shapingNotes": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "imagePromptShape", "motionPromptShape", "renderTarget", "shapingNotes" ], "additionalProperties": false }, "sceneOutline": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "sceneOrder": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "purpose": { "type": "string", "minLength": 1, "maxLength": 4000 }, "durationMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "sceneOrder", "title", "purpose", "durationMs" ], "additionalProperties": false } }, "distributionNotes": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Creative Plan Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/creative-plan. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.scenes.update Call PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}. Contract: PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: briefs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "sceneId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "maxLength": 255 }, "objective": { "type": "string", "maxLength": 4000 }, "visualPrompt": { "type": "string", "maxLength": 4000 }, "narration": { "type": "string", "maxLength": 4000 }, "durationMs": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "transitionLabel": { "anyOf": [ { "type": "string", "maxLength": 255 }, { "type": "null" } ] }, "motionRecommendation": { "type": "string", "maxLength": 4000 }, "transitionRecommendation": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "captionReference": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] } }, "required": [ "workspaceSlug", "projectId", "sceneId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Scenes Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/workspaces/{workspaceSlug}/projects/{projectId}/scenes/{sceneId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.bootstrap Get the signed workspace bootstrap payload for this service. Contract: GET /api/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/bootstrap without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### identity.get Get the authenticated Social Studio user and organization. Contract: GET /api/whoami Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get current identity.", "additionalProperties": true } ``` Effects: Reads state through GET /api/whoami without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.list List Social Studio projects. Contract: GET /api/workspaces/{workspaceSlug}/projects Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List projects.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/projects without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### planning.get Get project planning data. Contract: GET /api/workspaces/{workspaceSlug}/projects/{projectId}/planning Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: briefs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get project planning.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/planning without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### generation.status Get generation status for a project. Contract: GET /api/workspaces/{workspaceSlug}/projects/{projectId}/generation/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get generation status.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/generation/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### assets.list List assets generated for a project. Contract: GET /api/workspaces/{workspaceSlug}/projects/{projectId}/assets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "sceneId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List assets.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/assets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### assets.upload Upload an image, video, audio file, or PDF into a Social Studio project. Contract: POST /api/workspaces/{workspaceSlug}/projects/{projectId}/assets/upload Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceSlug": "example", "projectId": "example", "contentBase64": "example", "contentType": "image/png", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 35000000 }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "image/gif", "image/svg+xml", "video/mp4", "video/webm", "video/quicktime", "audio/mpeg", "audio/wav", "audio/mp4", "application/pdf" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "title": { "type": "string", "minLength": 1, "maxLength": 255 }, "sceneId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/workspaces/{workspaceSlug}/projects/{projectId}/assets/upload. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operator.summary Get operator summary for a workspace. Contract: GET /api/workspaces/{workspaceSlug}/operator/summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get operator summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/operator/summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### billing.current_plan.get Call GET /api/workspaces/{workspaceSlug}/billing/current-plan. Contract: GET /api/workspaces/{workspaceSlug}/billing/current-plan Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Current Plan Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/billing/current-plan without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### billing.usage_summary.get Call GET /api/workspaces/{workspaceSlug}/billing/usage-summary. Contract: GET /api/workspaces/{workspaceSlug}/billing/usage-summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Usage Summary Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/billing/usage-summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### operator.audit_events.list Call GET /api/workspaces/{workspaceSlug}/security/audit-events. Contract: GET /api/workspaces/{workspaceSlug}/security/audit-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Operator Audit Events List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/security/audit-events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### assets.content.get Call GET /api/workspaces/{workspaceSlug}/assets/{assetId}/content. Contract: GET /api/workspaces/{workspaceSlug}/assets/{assetId}/content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example", "assetId": "example", "token": "example", "expiresAt": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "assetId", "token", "expiresAt" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assets Content Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/assets/{assetId}/content without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### assets.preview.get Call GET /api/workspaces/{workspaceSlug}/assets/{assetId}/preview. Contract: GET /api/workspaces/{workspaceSlug}/assets/{assetId}/preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example", "assetId": "example", "token": "example", "expiresAt": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "assetId": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "assetId", "token", "expiresAt" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assets Preview Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/assets/{assetId}/preview without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### generation.model_options.list Call GET /api/workspaces/{workspaceSlug}/generation/model-options. Contract: GET /api/workspaces/{workspaceSlug}/generation/model-options Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: generation:write Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generation Model Options List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/generation/model-options without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.creative_resources.list Call GET /api/workspaces/{workspaceSlug}/creative-resources. Contract: GET /api/workspaces/{workspaceSlug}/creative-resources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Workspace Creative Resources List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/creative-resources without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### settings.status.get Call GET /api/workspaces/{workspaceSlug}/settings/status. Contract: GET /api/workspaces/{workspaceSlug}/settings/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Settings Status Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/settings/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.sync.get Call GET /api/workspaces/{workspaceSlug}/projects/{projectId}/sync. Contract: GET /api/workspaces/{workspaceSlug}/projects/{projectId}/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceSlug": "example", "projectId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceSlug": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceSlug", "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Sync Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceSlug}/projects/{projectId}/sync without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## Socialize source contract Human reference: https://docs.topolo.app/systems/socialize Machine reference: https://docs.topolo.app/machine/systems/socialize.json Source revisions: apps/TopoloSocialize@8a2994cc3a2d7b517df53e4a14f0fdb503ce8fe5 Deploy targets: 3; implemented actions: 173; declared actions: 173; uncatalogued served routes: 0; mobile contracts: 1; route signals: 236. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.summary Get social analytics summary. Contract: GET /api/analytics/summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 1, "startDate": "example", "endDate": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get analytics summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/analytics/summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### posts.list List social posts. Contract: GET /api/posts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "authorId": "example", "status": "draft", "platform": "twitter" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "authorId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published", "failed", "cancelled", "archived" ] }, "platform": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "campaignId": { "type": "string", "minLength": 1 }, "threadId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List posts.", "additionalProperties": true } ``` Effects: Reads state through GET /api/posts without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### posts.create Create a social post. Contract: POST /api/posts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "content": "A concise launch update.", "platform": "twitter", "scheduledFor": "2026-08-01T09:00:00.000Z" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 63206 }, "platform": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "scheduledFor": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "publishNow": { "type": "boolean" }, "mediaUrl": { "type": "string", "format": "uri" }, "mediaType": { "type": "string", "enum": [ "image", "video", "gif" ] }, "placement": { "type": "string", "enum": [ "feed", "story" ] }, "publishMode": { "type": "string", "enum": [ "auto", "manual" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "content", "platform" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "authorId": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "status": { "type": "string" }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishResultAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "content", "authorId", "brandId", "platform", "status", "scheduledFor", "publishedAt", "failedAt", "failureCode", "failureMessage", "lastPublishAttemptAt", "lastPublishResultAt", "mediaUrl", "mediaType", "mediaThumbnailUrl", "metadata", "createdAt", "updatedAt" ], "additionalProperties": false } ``` Effects: Creates one draft or scheduled social post for the active brand. Verification: Call posts.get with the returned id and confirm status, platform, and scheduledFor. Recovery: 403 forbidden: Select a brand bound to the credential and retry. ### posts.get Call GET /api/posts/{id}. Contract: GET /api/posts/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string" }, "authorId": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "status": { "type": "string" }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publishedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "failureMessage": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishAttemptAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastPublishResultAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaThumbnailUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "content", "authorId", "brandId", "platform", "status", "scheduledFor", "publishedAt", "failedAt", "failureCode", "failureMessage", "lastPublishAttemptAt", "lastPublishResultAt", "mediaUrl", "mediaType", "mediaThumbnailUrl", "metadata", "createdAt", "updatedAt" ], "additionalProperties": false } ``` Effects: Reads state through GET /api/posts/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### posts.update Call PUT /api/posts/{id}. Contract: PUT /api/posts/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1, "maxLength": 10000 }, "scheduledFor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "draft", "scheduled", "published", "failed", "cancelled" ] }, "unschedule": { "type": "boolean" }, "platform": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "placement": { "anyOf": [ { "type": "string", "enum": [ "feed", "story" ] }, { "type": "null" } ] }, "publishMode": { "anyOf": [ { "type": "string", "enum": [ "auto", "manual" ] }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Posts Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/posts/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### posts.delete Call DELETE /api/posts/{id}. Contract: DELETE /api/posts/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Posts Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/posts/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### posts.publish Call POST /api/posts/{id}/publish. Contract: POST /api/posts/{id}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Posts Publish.", "additionalProperties": true } ``` Effects: May change state through POST /api/posts/{id}/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.list List social campaigns. Contract: GET /api/campaigns Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "createdBy": "example", "status": "draft", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "completed", "cancelled" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List campaigns.", "additionalProperties": true } ``` Effects: Reads state through GET /api/campaigns without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### campaigns.create Create a social campaign. Contract: POST /api/campaigns Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "Launch campaign", "status": "scheduled", "platforms": [ "twitter", "linkedin" ], "variants": [ { "name": "Primary", "weight": 100, "content": { "text": "Launch update" } } ], "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z", "timezone": "Asia/Dubai", "scheduleDays": [ "monday", "wednesday", "friday" ], "scheduleTimes": [ "09:00" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 1000 }, "platforms": { "minItems": 1, "type": "array", "items": { "type": "string", "enum": [ "twitter", "linkedin", "facebook", "instagram", "tiktok", "threads", "youtube" ] } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "postId": { "type": "string", "minLength": 1 }, "content": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 63206 }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "media": { "type": "array", "items": { "type": "string" } }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "text" ], "additionalProperties": false }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "weight" ], "additionalProperties": false } }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "windowEndDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } }, "scheduleTimes": { "type": "array", "items": { "type": "string", "pattern": "^\\d{2}:\\d{2}$" } }, "status": { "type": "string", "enum": [ "draft", "scheduled" ] } }, "required": [ "name", "platforms" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resumedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "weight": { "type": "number" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "weight", "postId" ], "additionalProperties": false } }, "scheduledPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "scheduledFor": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "platform", "scheduledFor", "status" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "createdBy", "status", "windowStartDate", "windowEndDate", "paused", "pausedAt", "resumedAt", "variants", "createdAt", "updatedAt" ], "additionalProperties": false } ``` Effects: Creates campaign variants for the active brand. When status=scheduled, materializes one durable post per cadence slot and enabled platform. Verification: Call campaigns.get and posts.list with campaignId; scheduled campaigns must return concrete scheduled posts. Recovery: 400 validation_error: Correct platform, variant weights, window, timezone, days, and times. ### campaigns.schedule Call POST /api/campaigns/{id}/schedule. Contract: POST /api/campaigns/{id}/schedule Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "campaign_example", "windowStartDate": "2026-08-01T00:00:00.000Z", "windowEndDate": "2026-08-08T23:59:59.000Z" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "windowStartDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, "windowEndDate": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "id", "windowStartDate", "windowEndDate" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resumedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "weight": { "type": "number" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "weight", "postId" ], "additionalProperties": false } }, "scheduledPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "scheduledFor": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "platform", "scheduledFor", "status" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "createdBy", "status", "windowStartDate", "windowEndDate", "paused", "pausedAt", "resumedAt", "variants", "createdAt", "updatedAt" ], "additionalProperties": false } ``` Effects: Transitions a draft campaign to scheduled and idempotently materializes its publish occurrences. Verification: Confirm scheduledPosts is non-empty and call posts.list with campaignId. Recovery: 400 validation_error: Ensure the campaign has content variants, enabled platforms, and cadence slots inside the window. 403 forbidden: Use a campaign owned by the credential-bound brand. ### brands.list List social brands/accounts. Contract: GET /api/brands Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List brands.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brands without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brands.create Create a social brand/account. Contract: POST /api/brands Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "Ashley Lane - Topolo Founder", "description": "Founder-led social presence for Topolo." } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "isDefault": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "logoUrl": { "type": "string" }, "memberCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "organizationId": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "description", "logoUrl", "memberCount", "organizationId", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "data" ], "additionalProperties": false } ``` Effects: Creates canonical workspace identity in Topolo Auth for Socialize. Creates the Socialize-owned brand profile mirror for that workspace. Verification: Call brands.list and confirm the returned workspace id appears exactly once. Recovery: 403 forbidden: Confirm the caller has workspace:write for Socialize and the organization can create another workspace. 409 workspace_creation_conflict: List Socialize brands before retrying so a successful creation is not duplicated. ### workspaces.delete Delete an empty non-default Socialize workspace. Contract: DELETE /api/workspaces/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.get Get a brand by id. Contract: GET /api/brands/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/brands/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.generate_content Generate social content with AI. Contract: POST /api/ai/generate-content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "prompt": "examplexxx" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prompt": { "type": "string", "minLength": 10, "maxLength": 10000 }, "contentTypeId": { "type": "string", "minLength": 1 }, "maxTokens": { "type": "number", "minimum": 100, "maximum": 4000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 1 }, "channel": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "audience": { "type": "string", "maxLength": 500 }, "objective": { "type": "string", "maxLength": 500 }, "claimIds": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1 } }, "ctaId": { "type": "string", "minLength": 1 } }, "required": [ "prompt" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate content.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/generate-content. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### posts.archive Archive a Socialize post. Contract: POST /api/posts/{id}/archive Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Archive post.", "additionalProperties": true } ``` Effects: May change state through POST /api/posts/{id}/archive. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### posts.reschedule Reschedule a Socialize post. Contract: PATCH /api/posts/{id}/reschedule Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "scheduledFor": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "scheduledFor": { "type": "string", "minLength": 1 } }, "required": [ "id", "scheduledFor" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reschedule post.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/posts/{id}/reschedule. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### posts.toggle_pause Toggle pause on a Socialize post. Contract: PATCH /api/posts/{id}/toggle-pause Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "paused": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "paused": { "type": "boolean" } }, "required": [ "id", "paused" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Toggle post pause.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/posts/{id}/toggle-pause. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_ops.queue.get Get the Socialize content ops queue. Contract: GET /api/content-ops/queue Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "channel": "example", "status": "example", "approval_state": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "approval_state": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get content ops queue.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-ops/queue without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_ops.daily.get Get Socialize daily content ops summary. Contract: GET /api/content-ops/daily Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "date": "example", "utc_offset": "example", "queue_limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "date": { "type": "string", "minLength": 1 }, "utc_offset": { "type": "string", "minLength": 1 }, "queue_limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get daily content ops.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-ops/daily without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_ops.events.list List Socialize content ops events. Contract: GET /api/content-ops/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "date": "example", "utc_offset": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "date": { "type": "string", "minLength": 1 }, "utc_offset": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List content ops events.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-ops/events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_ops.deck.get Get the Socialize content ops deck. Contract: GET /api/content-ops/deck Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "platform": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get content ops deck.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-ops/deck without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_ops.items.get Get a Socialize content ops item. Contract: GET /api/content-ops/items/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get content ops item.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-ops/items/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_ops.items.update Update a Socialize content ops item. Contract: PATCH /api/content-ops/items/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "id", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update content ops item.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/content-ops/items/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_ops.items.approve Approve a Socialize content ops item. Contract: POST /api/content-ops/items/{id}/approve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Approve content ops item.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-ops/items/{id}/approve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_ops.items.reject Reject a Socialize content ops item. Contract: POST /api/content-ops/items/{id}/reject Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reject content ops item.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-ops/items/{id}/reject. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_ops.items.reschedule Reschedule a Socialize content ops item. Contract: POST /api/content-ops/items/{id}/reschedule Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "scheduled_at": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "scheduled_at": { "type": "string", "minLength": 1 } }, "required": [ "id", "scheduled_at" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reschedule content ops item.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-ops/items/{id}/reschedule. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_ops.items.retry Retry a Socialize content ops item. Contract: POST /api/content-ops/items/{id}/retry Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Retry content ops item.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-ops/items/{id}/retry. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.get Get a Socialize campaign. Contract: GET /api/campaigns/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "brandId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "createdBy": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "paused": { "type": "boolean" }, "pausedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resumedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "weight": { "type": "number" }, "postId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "weight", "postId" ], "additionalProperties": false } }, "scheduledPosts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "scheduledFor": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id", "platform", "scheduledFor", "status" ], "additionalProperties": false } }, "createdAt": { "type": "string" }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "createdBy", "status", "windowStartDate", "windowEndDate", "paused", "pausedAt", "resumedAt", "variants", "createdAt", "updatedAt" ], "additionalProperties": false } ``` Effects: Reads state through GET /api/campaigns/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### campaigns.update Update a Socialize campaign. Contract: PUT /api/campaigns/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string" }, "status": { "type": "string" }, "goals": { "type": "array", "items": { "type": "string" } }, "tags": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform", "enabled", "settings" ], "additionalProperties": false } }, "windowStartDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "windowEndDate": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "timezone": { "type": "string" }, "scheduleDays": { "type": "array", "items": { "type": "string" } }, "scheduleTimes": { "type": "array", "items": { "type": "string" } }, "variants": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "weight": { "type": "number", "minimum": 0, "maximum": 100 }, "postId": { "type": "string", "minLength": 1 }, "content": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 63206 }, "mediaUrls": { "type": "array", "items": { "type": "string", "format": "uri" } }, "media": { "type": "array", "items": { "type": "string" } }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "text" ], "additionalProperties": false }, "hashtags": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "weight" ], "additionalProperties": false } } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update campaign.", "additionalProperties": true } ``` Effects: May change state through PUT /api/campaigns/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.delete Delete a Socialize campaign. Contract: DELETE /api/campaigns/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete campaign.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/campaigns/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.activate Activate a Socialize campaign. Contract: POST /api/campaigns/{id}/activate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Activate campaign.", "additionalProperties": true } ``` Effects: May change state through POST /api/campaigns/{id}/activate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.complete Complete a Socialize campaign. Contract: POST /api/campaigns/{id}/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete campaign.", "additionalProperties": true } ``` Effects: May change state through POST /api/campaigns/{id}/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.cancel Cancel a Socialize campaign. Contract: POST /api/campaigns/{id}/cancel Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Cancel campaign.", "additionalProperties": true } ``` Effects: May change state through POST /api/campaigns/{id}/cancel. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.pause Pause a Socialize campaign. Contract: POST /api/campaigns/{id}/pause Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Pause campaign.", "additionalProperties": true } ``` Effects: May change state through POST /api/campaigns/{id}/pause. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.resume Resume a Socialize campaign. Contract: POST /api/campaigns/{id}/resume Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: calendar:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Resume campaign.", "additionalProperties": true } ``` Effects: May change state through POST /api/campaigns/{id}/resume. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.analytics.get Get Socialize campaign analytics. Contract: GET /api/campaigns/{id}/analytics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get campaign analytics.", "additionalProperties": true } ``` Effects: Reads state through GET /api/campaigns/{id}/analytics without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### campaigns.analytics_engine.get Get Socialize campaign analytics engine data. Contract: GET /api/campaigns/{id}/analytics/engine Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get campaign analytics engine.", "additionalProperties": true } ``` Effects: Reads state through GET /api/campaigns/{id}/analytics/engine without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### campaigns.variants.analytics.get Get Socialize campaign variant analytics. Contract: GET /api/campaigns/{id}/analytics/variants/{variantId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "variantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "variantId": { "type": "string", "minLength": 1 }, "days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startDate": { "type": "string", "minLength": 1 }, "endDate": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 } }, "required": [ "id", "variantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get campaign variant analytics.", "additionalProperties": true } ``` Effects: Reads state through GET /api/campaigns/{id}/analytics/variants/{variantId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### scheduler.process Process Socialize scheduled posts. Contract: POST /api/scheduler/process Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Process scheduler.", "additionalProperties": true } ``` Effects: May change state through POST /api/scheduler/process. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### scheduler.status.get Get Socialize scheduler status. Contract: GET /api/scheduler/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get scheduler status.", "additionalProperties": true } ``` Effects: Reads state through GET /api/scheduler/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### scheduler.drafts.from_trend Create a Socialize scheduler draft from a trend. Contract: POST /api/scheduler/drafts/from-trend Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "trendId": "example", "platform": "linkedin", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "trendId": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "linkedin", "x", "instagram", "tiktok", "youtube" ] }, "content": { "type": "string", "minLength": 1 }, "hashtags": { "type": "array", "items": { "type": "string" } }, "scheduledFor": { "type": "string", "minLength": 1 } }, "required": [ "trendId", "platform", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create draft from trend.", "additionalProperties": true } ``` Effects: May change state through POST /api/scheduler/drafts/from-trend. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.upload_url.create Create a Socialize media upload URL. Contract: POST /api/media/upload Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "filename": "example", "contentType": "example", "size": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "contentType": { "type": "string", "minLength": 1 }, "size": { "type": "number", "exclusiveMinimum": 0, "maximum": 524288000 }, "width": { "type": "number", "exclusiveMinimum": 0 }, "height": { "type": "number", "exclusiveMinimum": 0 }, "key": { "type": "string", "minLength": 1 } }, "required": [ "filename", "contentType", "size" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create media upload URL.", "additionalProperties": true } ``` Effects: May change state through POST /api/media/upload. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.list List Socialize media. Contract: GET /api/media/list Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "collection": "example", "tag": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string", "minLength": 1 }, "collection": { "type": "string", "minLength": 1 }, "tag": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "all", "image", "video", "audio", "document" ] }, "sort": { "type": "string", "enum": [ "date", "name", "size", "type" ] }, "order": { "type": "string", "enum": [ "asc", "desc" ] }, "status": { "type": "string", "enum": [ "active", "archived", "deleted" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List media.", "additionalProperties": true } ``` Effects: Reads state through GET /api/media/list without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### media.bulk Run a Socialize bulk media operation. Contract: POST /api/media/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "mediaIds": [ "example" ], "action": "delete" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "action": { "type": "string", "enum": [ "delete", "archive", "restore", "tag", "move" ] }, "tagId": { "type": "string", "minLength": 1 }, "collectionId": { "type": "string", "minLength": 1 } }, "required": [ "mediaIds", "action" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Run bulk media operation.", "additionalProperties": true } ``` Effects: May change state through POST /api/media/bulk. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.tags.list List Socialize media tags. Contract: GET /api/media/tags Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List media tags.", "additionalProperties": true } ``` Effects: Reads state through GET /api/media/tags without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### media.tags.create Create a Socialize media tag. Contract: POST /api/media/tags Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 50 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create media tag.", "additionalProperties": true } ``` Effects: May change state through POST /api/media/tags. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.tags.delete Delete a Socialize media tag. Contract: DELETE /api/media/tags/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete media tag.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/media/tags/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.collections.list List Socialize media collections. Contract: GET /api/media/collections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List media collections.", "additionalProperties": true } ``` Effects: Reads state through GET /api/media/collections without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### media.collections.create Create a Socialize media collection. Contract: POST /api/media/collections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "parentId": { "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create media collection.", "additionalProperties": true } ``` Effects: May change state through POST /api/media/collections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.collections.delete Delete a Socialize media collection. Contract: DELETE /api/media/collections/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete media collection.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/media/collections/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.metadata.get Get Socialize media metadata. Contract: GET /api/media/{id}/metadata Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get media metadata.", "additionalProperties": true } ``` Effects: Reads state through GET /api/media/{id}/metadata without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### media.upload.complete Complete a Socialize media upload. Contract: POST /api/media/{id}/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete media upload.", "additionalProperties": true } ``` Effects: May change state through POST /api/media/{id}/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### media.metadata.bulk_get Bulk get Socialize media metadata. Contract: POST /api/media/metadata Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "mediaIds": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaIds": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "mediaIds" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk get media metadata.", "additionalProperties": true } ``` Effects: May change state through POST /api/media/metadata. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### flags.list List Socialize flags. Contract: GET /api/flags Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List flags.", "additionalProperties": true } ``` Effects: Reads state through GET /api/flags without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### flags.create Create a Socialize flag. Contract: POST /api/flags Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "description": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "rolloutPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "targetRoles": { "type": "array", "items": { "type": "string" } }, "targetEmails": { "type": "array", "items": { "type": "string" } }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "name", "description" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create flag.", "additionalProperties": true } ``` Effects: May change state through POST /api/flags. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### flags.me.list List current-user Socialize flags. Contract: GET /api/flags/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my flags.", "additionalProperties": true } ``` Effects: Reads state through GET /api/flags/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### flags.user.list List Socialize flags for a user. Contract: GET /api/flags/user/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user flags.", "additionalProperties": true } ``` Effects: Reads state through GET /api/flags/user/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### flags.user.set Set a Socialize flag for a user. Contract: PUT /api/flags/{flagId}/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "flagId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "flagId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" } }, "required": [ "flagId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set user flag.", "additionalProperties": true } ``` Effects: May change state through PUT /api/flags/{flagId}/users/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### flags.user.remove Remove a Socialize flag for a user. Contract: DELETE /api/flags/{flagId}/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "flagId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "flagId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "flagId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove user flag.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/flags/{flagId}/users/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### flags.get Get a Socialize flag. Contract: GET /api/flags/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get flag.", "additionalProperties": true } ``` Effects: Reads state through GET /api/flags/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### flags.update Update a Socialize flag. Contract: PATCH /api/flags/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "rolloutPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "targetRoles": { "type": "array", "items": { "type": "string" } }, "targetEmails": { "type": "array", "items": { "type": "string" } }, "environments": { "type": "array", "items": { "type": "string" } } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update flag.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/flags/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### flags.delete Delete a Socialize flag. Contract: DELETE /api/flags/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete flag.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/flags/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization.create Create a Socialize organization brand. Contract: POST /api/organization Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "isDefault": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization brand.", "additionalProperties": true } ``` Effects: May change state through POST /api/organization. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization.get Get the Socialize organization brand. Contract: GET /api/organization Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization brand.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization.accept_invite Accept a Socialize organization invite. Contract: POST /api/organization/accept-invite Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "token": "examplexxx" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "token": { "type": "string", "minLength": 10, "maxLength": 100 } }, "required": [ "token" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Accept organization invite.", "additionalProperties": true } ``` Effects: May change state through POST /api/organization/accept-invite. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.update Update a Socialize brand. Contract: PUT /api/brands/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "logoUrl": { "type": "string", "format": "uri" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update brand.", "additionalProperties": true } ``` Effects: May change state through PUT /api/brands/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.transfer_organization Transfer a Socialize brand organization. Contract: POST /api/brands/{id}/transfer-organization Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "targetOrganizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "targetOrganizationId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "id", "targetOrganizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Transfer brand organization.", "additionalProperties": true } ``` Effects: May change state through POST /api/brands/{id}/transfer-organization. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.members.list List Socialize brand members. Contract: GET /api/brands/{id}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List brand members.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brands/{id}/members without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brands.join_requests.list List Socialize brand join requests. Contract: GET /api/brands/{id}/join-requests Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List brand join requests.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brands/{id}/join-requests without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### join_requests.approve Approve a Socialize join request. Contract: PUT /api/join-requests/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Approve join request.", "additionalProperties": true } ``` Effects: May change state through PUT /api/join-requests/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### join_requests.reject Reject a Socialize join request. Contract: DELETE /api/join-requests/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reject join request.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/join-requests/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.get Get a Socialize organization. Contract: GET /api/organizations/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.update Update a Socialize organization. Contract: PUT /api/organizations/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "logoUrl": { "type": "string", "format": "uri" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.members.list List Socialize organization members. Contract: GET /api/organizations/{id}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization members.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{id}/members without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.members.invite Invite a Socialize organization member. Contract: POST /api/organizations/{id}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "email": "user@example.com", "role": "admin" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "email": { "type": "string", "maxLength": 255, "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 30 } }, "required": [ "id", "email", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Invite organization member.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{id}/members. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.members.remove Remove a Socialize organization member. Contract: DELETE /api/organizations/{id}/members/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "id", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove organization member.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{id}/members/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.members.update_role Update a Socialize organization member role. Contract: PUT /api/organizations/{id}/members/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "userId": "example", "role": "admin" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "enum": [ "admin", "member", "viewer" ] } }, "required": [ "id", "userId", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization member role.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{id}/members/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.invites.list List Socialize organization invites. Contract: GET /api/organizations/{id}/invites Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization invites.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{id}/invites without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.invites.cancel Cancel a Socialize organization invite. Contract: DELETE /api/organizations/{id}/invites/{inviteId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "inviteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "inviteId": { "type": "string", "minLength": 1 } }, "required": [ "id", "inviteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Cancel organization invite.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{id}/invites/{inviteId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.activity.list List Socialize organization activity. Contract: GET /api/organizations/{id}/activity Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization activity.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{id}/activity without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.export Export organization-authored Socialize data without provider credentials or media binaries. Contract: GET /api/organizations/{id}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{id}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase organization-authored Socialize data, provider connections, and media objects after active publishing work is cleared. Contract: DELETE /api/organizations/{id}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "id", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{id}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### preferences.get Get Socialize user preferences. Contract: GET /api/user/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user preferences.", "additionalProperties": true } ``` Effects: Reads state through GET /api/user/preferences without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### preferences.update Update Socialize user preferences. Contract: PUT /api/user/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "theme": "example", "language": "example", "timezone": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "theme": { "type": "string" }, "language": { "type": "string" }, "timezone": { "type": "string" }, "notifications": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "dashboard": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "calendar": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "analytics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update user preferences.", "additionalProperties": true } ``` Effects: May change state through PUT /api/user/preferences. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.list List Socialize integrations. Contract: GET /api/integrations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List integrations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/integrations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### integrations.connect Start a Socialize integration connection. Contract: POST /api/integrations/{platform}/connect Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "platform": "linkedin" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string", "minLength": 1 }, "callbackUrl": { "type": "string", "format": "uri" } }, "required": [ "platform" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "authUrl": { "type": "string", "format": "uri" }, "state": { "type": "string", "minLength": 1 }, "expiresAt": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" } }, "required": [ "authUrl", "state", "expiresAt" ], "additionalProperties": false } ``` Effects: Creates a short-lived OAuth state and returns the provider authorization URL; it does not complete the connection. Verification: Open authUrl for the user, complete provider consent, then call integrations.list and confirm an active connection for the selected provider. Recovery: 400 unsupported_platform: Call integrations.list and choose a connectable provider id. 409 integration_misconfigured: Configure the provider OAuth credential in Nexus for Socialize and this environment. 503 integration_dependency_unavailable: Retry the action. If it continues, inspect Auth service-token exchange and Nexus availability using the request ID. ### integrations.linkedin_organization.update Update Socialize LinkedIn organization. Contract: PUT /api/integrations/linkedin/organization Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update LinkedIn organization.", "additionalProperties": true } ``` Effects: May change state through PUT /api/integrations/linkedin/organization. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.facebook_page.update Update Socialize Facebook page. Contract: PUT /api/integrations/facebook/page Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "pageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pageId": { "type": "string", "minLength": 1 } }, "required": [ "pageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update Facebook page.", "additionalProperties": true } ``` Effects: May change state through PUT /api/integrations/facebook/page. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.nickname.update Update a Socialize integration nickname. Contract: PUT /api/integrations/{id}/nickname Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "nickname": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "nickname": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "nickname" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update integration nickname.", "additionalProperties": true } ``` Effects: May change state through PUT /api/integrations/{id}/nickname. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.disconnect Disconnect a Socialize integration. Contract: DELETE /api/integrations/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Disconnect integration.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/integrations/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.generate_image Generate a Socialize image. Contract: POST /api/ai/generate-image Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "prompt": "examplexxx" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prompt": { "type": "string", "minLength": 10, "maxLength": 1000 }, "negativePrompt": { "type": "string", "maxLength": 500 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4" ] }, "numberOfImages": { "type": "number", "minimum": 1, "maximum": 4 }, "style": { "type": "string", "enum": [ "photorealistic", "digital_art", "watercolor", "oil_painting", "sketch" ] }, "preprocessPrompt": { "type": "boolean" }, "postContent": { "type": "string", "maxLength": 2000 }, "provider": { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, "model": { "type": "string", "maxLength": 200 } }, "required": [ "prompt" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate image.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/generate-image. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.generate_programmatic_image Generate a Socialize programmatic image. Contract: POST /api/ai/generate-programmatic-image Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "content": { "type": "string", "minLength": 1, "maxLength": 2000 }, "template": { "type": "string", "enum": [ "quote", "stat", "comparison", "announcement", "list", "pricing", "thread_hook", "milestone" ] }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "4:5" ] }, "channel": { "type": "string", "enum": [ "twitter", "x", "linkedin", "linkedin_company", "facebook", "instagram", "threads", "tiktok", "youtube" ] }, "claimIds": { "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 1 } }, "ctaId": { "type": "string", "minLength": 1 } }, "required": [ "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate programmatic image.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/generate-programmatic-image. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.programmatic_config.get Get Socialize programmatic image config. Contract: GET /api/ai/programmatic-config Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get programmatic config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/programmatic-config without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.update_image Update a Socialize item image. Contract: POST /api/ai/update-image Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "itemType": "suggestion", "itemId": "example", "imageUrl": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "itemType": { "type": "string", "enum": [ "suggestion", "post" ] }, "itemId": { "type": "string", "minLength": 1 }, "imageUrl": { "type": "string", "minLength": 1 } }, "required": [ "itemType", "itemId", "imageUrl" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update image.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/update-image. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.config.get Get Socialize AI config. Contract: GET /api/ai/config Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get AI config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/config without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.images.list List Socialize AI images. Contract: GET /api/ai/images Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "contentTypeId": "example", "limit": 1, "offset": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentTypeId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "favoritesOnly": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List AI images.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/images without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.library.list List Socialize AI library items. Contract: GET /api/ai/library Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "contentTypeId": "example", "limit": 1, "offset": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentTypeId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "favoritesOnly": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List AI library.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/library without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.library.create Create a Socialize AI library item. Contract: POST /api/ai/library Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contentTypeId": "example", "inputs": {}, "output": {}, "tone": "example", "length": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentTypeId": { "type": "string", "minLength": 1 }, "inputs": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "output": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "tone": { "type": "string", "minLength": 1 }, "length": { "type": "string", "minLength": 1 }, "brandVoiceSnapshot": {}, "authenticityControlsSnapshot": {}, "aiLikenessScore": {}, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "isFavorite": { "type": "boolean" }, "mediaUrl": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mediaType": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "contentTypeId", "inputs", "output", "tone", "length" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create AI library item.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/library. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.library.delete Delete a Socialize AI library item. Contract: DELETE /api/ai/library/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete AI library item.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/ai/library/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.library.favorite Toggle favorite on a Socialize AI library item. Contract: PATCH /api/ai/library/{id}/favorite Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Favorite AI library item.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/ai/library/{id}/favorite. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.trends.list List Socialize AI trends. Contract: GET /api/ai/trends Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "platforms": "example", "region": "global", "language": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platforms": { "type": "string" }, "region": { "type": "string", "enum": [ "global", "us", "uk", "eu", "uae", "india", "asia-pacific", "latam" ] }, "language": { "type": "string", "maxLength": 10 }, "topics": { "type": "string" }, "timeWindow": { "type": "string", "enum": [ "24h", "7d" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "forceRefresh": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List AI trends.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/trends without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.trends.saved.list List saved Socialize AI trends. Contract: GET /api/ai/trends/saved Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List saved AI trends.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/trends/saved without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.trends.save Save a Socialize AI trend. Contract: POST /api/ai/trends/save Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "trendId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "trendId": { "type": "string", "minLength": 1 }, "notes": { "type": "string", "maxLength": 500 } }, "required": [ "trendId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Save AI trend.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/trends/save. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.trends.health.get Get Socialize trend provider health. Contract: GET /api/ai/trends/health Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get trend provider health.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/trends/health without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.x_research.get Get Socialize X research. Contract: GET /api/ai/x-research Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "handle": "example", "limit": 1, "days": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "handle": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 }, "days": { "type": "integer", "minimum": 1, "maximum": 30 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get X research.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/x-research without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### trends.list List Socialize content strategy trends. Contract: GET /api/trends Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "source": "example", "limit": 1, "offset": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List trends.", "additionalProperties": true } ``` Effects: Reads state through GET /api/trends without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.trends.get Get a Socialize AI trend. Contract: GET /api/ai/trends/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get AI trend.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/trends/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.trends.generate Generate Socialize content from an AI trend. Contract: POST /api/ai/trends/{id}/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "platform": "linkedin" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "linkedin", "x", "instagram", "tiktok", "youtube" ] }, "selectedAngleIndex": { "type": "number" }, "selectedHookIndex": { "type": "number" }, "tone": { "type": "string" }, "length": { "type": "string" }, "brandVoice": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "platform" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate from AI trend.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/trends/{id}/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.trends.saved.delete Delete a saved Socialize AI trend. Contract: DELETE /api/ai/trends/saved/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete saved AI trend.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/ai/trends/saved/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_voice.presets.list List Socialize brand voice presets. Contract: GET /api/brand-voice/presets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List brand voice presets.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-voice/presets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### integrations.linkedin_company_organization.update Call PUT /api/integrations/linkedin_company/organization. Contract: PUT /api/integrations/linkedin_company/organization Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations Linkedin Company Organization Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/integrations/linkedin_company/organization. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_voice.presets.builtin.list Call GET /api/brand-voice/presets/builtin. Contract: GET /api/brand-voice/presets/builtin Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Builtin List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-voice/presets/builtin without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_voice.presets.default.get Call GET /api/brand-voice/presets/default. Contract: GET /api/brand-voice/presets/default Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Default Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-voice/presets/default without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_voice.presets.create Call POST /api/brand-voice/presets. Contract: POST /api/brand-voice/presets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "tone": { "type": "string" }, "audience": { "type": "string" }, "styleRules": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } }, "isDefault": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-voice/presets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_voice.presets.set_default Call POST /api/brand-voice/presets/{id}/default. Contract: POST /api/brand-voice/presets/{id}/default Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Set Default.", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-voice/presets/{id}/default. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_voice.presets.duplicate Call POST /api/brand-voice/presets/{id}/duplicate. Contract: POST /api/brand-voice/presets/{id}/duplicate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Duplicate.", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-voice/presets/{id}/duplicate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_voice.presets.get Call GET /api/brand-voice/presets/{id}. Contract: GET /api/brand-voice/presets/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-voice/presets/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_voice.presets.update Call PUT /api/brand-voice/presets/{id}. Contract: PUT /api/brand-voice/presets/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "tone": { "type": "string" }, "audience": { "type": "string" }, "styleRules": { "type": "array", "items": { "type": "string" } }, "examples": { "type": "array", "items": { "type": "string" } }, "isDefault": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/brand-voice/presets/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_voice.presets.delete Call DELETE /api/brand-voice/presets/{id}. Contract: DELETE /api/brand-voice/presets/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Presets Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/brand-voice/presets/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_voice.audit.list Call GET /api/brand-voice/audit. Contract: GET /api/brand-voice/audit Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Voice Audit List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-voice/audit without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand.ctas.list Call GET /api/brand/ctas. Contract: GET /api/brand/ctas Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Ctas List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand/ctas without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand.ctas.create Call POST /api/brand/ctas. Contract: POST /api/brand/ctas Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "label": "example", "url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "category": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "number" } }, "required": [ "label", "url" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Ctas Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/brand/ctas. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand.ctas.update Call PUT /api/brand/ctas/{id}. Contract: PUT /api/brand/ctas/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "category": { "type": "string" }, "keywords": { "type": "array", "items": { "type": "string" } }, "priority": { "type": "number" }, "isActive": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Ctas Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/brand/ctas/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand.ctas.delete Call DELETE /api/brand/ctas/{id}. Contract: DELETE /api/brand/ctas/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand Ctas Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/brand/ctas/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand.x_mentions.list Call GET /api/brand/x-mentions. Contract: GET /api/brand/x-mentions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand X Mentions List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand/x-mentions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand.x_mentions.create Call POST /api/brand/x-mentions. Contract: POST /api/brand/x-mentions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "entityName": "example", "xHandle": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entityName": { "type": "string", "minLength": 1 }, "xHandle": { "type": "string", "minLength": 1 }, "entityType": { "type": "string" }, "relationship": { "type": "string" }, "notes": { "type": "string" }, "autoTag": { "type": "boolean" } }, "required": [ "entityName", "xHandle" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand X Mentions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/brand/x-mentions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand.x_mentions.update Call PUT /api/brand/x-mentions/{id}. Contract: PUT /api/brand/x-mentions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "entityName": { "type": "string", "minLength": 1 }, "xHandle": { "type": "string", "minLength": 1 }, "entityType": { "type": "string" }, "relationship": { "type": "string" }, "notes": { "type": "string" }, "autoTag": { "type": "boolean" }, "isVerified": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand X Mentions Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/brand/x-mentions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand.x_mentions.delete Call DELETE /api/brand/x-mentions/{id}. Contract: DELETE /api/brand/x-mentions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brand X Mentions Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/brand/x-mentions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.engagement_targets.list Call GET /api/content-strategy/engagement-targets. Contract: GET /api/content-strategy/engagement-targets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "activeOnly": "true", "brandId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activeOnly": { "type": "string", "enum": [ "true", "false" ] }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Engagement Targets List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/engagement-targets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.engagement_targets.create Call POST /api/content-strategy/engagement-targets. Contract: POST /api/content-strategy/engagement-targets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "platform": "example", "username": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string" }, "username": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "platform", "username" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/engagement-targets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.engagement_targets.get Call GET /api/content-strategy/engagement-targets/{id}. Contract: GET /api/content-strategy/engagement-targets/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/engagement-targets/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.engagement_targets.update Call PUT /api/content-strategy/engagement-targets/{id}. Contract: PUT /api/content-strategy/engagement-targets/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "platform": { "type": "string" }, "username": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "notes": { "type": "string" }, "priority": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/content-strategy/engagement-targets/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.engagement_targets.delete Call DELETE /api/content-strategy/engagement-targets/{id}. Contract: DELETE /api/content-strategy/engagement-targets/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Engagement Targets Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/content-strategy/engagement-targets/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.topics.list Call GET /api/content-strategy/topics. Contract: GET /api/content-strategy/topics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "activeOnly": "true", "brandId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activeOnly": { "type": "string", "enum": [ "true", "false" ] }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Topics List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/topics without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.topics.create Call POST /api/content-strategy/topics. Contract: POST /api/content-strategy/topics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "topic": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "topic": { "type": "string", "minLength": 1 }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "topic" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Topics Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/topics. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.topics.update Call PUT /api/content-strategy/topics/{id}. Contract: PUT /api/content-strategy/topics/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "topic": { "type": "string", "minLength": 1 }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Topics Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/content-strategy/topics/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.topics.delete Call DELETE /api/content-strategy/topics/{id}. Contract: DELETE /api/content-strategy/topics/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Topics Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/content-strategy/topics/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.pillars.list Call GET /api/content-strategy/pillars. Contract: GET /api/content-strategy/pillars Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "activeOnly": "true", "brandId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "activeOnly": { "type": "string", "enum": [ "true", "false" ] }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Pillars List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/pillars without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.pillars.create Call POST /api/content-strategy/pillars. Contract: POST /api/content-strategy/pillars Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Pillars Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/pillars. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.pillars.update Call PUT /api/content-strategy/pillars/{id}. Contract: PUT /api/content-strategy/pillars/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "weight": { "type": "number" }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Pillars Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/content-strategy/pillars/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.pillars.delete Call DELETE /api/content-strategy/pillars/{id}. Contract: DELETE /api/content-strategy/pillars/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Pillars Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/content-strategy/pillars/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.platform_preferences.list Call GET /api/content-strategy/platform-preferences. Contract: GET /api/content-strategy/platform-preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Platform Preferences List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/platform-preferences without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.platform_preferences.create Call POST /api/content-strategy/platform-preferences. Contract: POST /api/content-strategy/platform-preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "platform": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "platform": { "type": "string" }, "enabled": { "type": "boolean" }, "postingFrequency": { "type": "string" }, "tone": { "type": "string" }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "platform" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Platform Preferences Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/platform-preferences. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.generate Call POST /api/content-strategy/generate. Contract: POST /api/content-strategy/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandId": "example", "goals": [ "example" ], "platforms": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "goals": { "type": "array", "items": { "type": "string" } }, "platforms": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Generate.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.suggestions.list Call GET /api/content-strategy/suggestions. Contract: GET /api/content-strategy/suggestions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "status": "example", "platform": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "brandId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Suggestions List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/suggestions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.suggestions.generate Call POST /api/content-strategy/suggestions/generate. Contract: POST /api/content-strategy/suggestions/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "count": 1, "platform": "example", "topic": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "platform": { "type": "string", "minLength": 1 }, "topic": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Suggestions Generate.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/suggestions/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.suggestions.generate_batch Call POST /api/content-strategy/suggestions/generate-batch. Contract: POST /api/content-strategy/suggestions/generate-batch Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "count": 1, "platforms": [ "example" ], "topics": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "platforms": { "type": "array", "items": { "type": "string" } }, "topics": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Suggestions Generate Batch.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/suggestions/generate-batch. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.suggestions.generate_from_trends Call POST /api/content-strategy/suggestions/generate-from-trends. Contract: POST /api/content-strategy/suggestions/generate-from-trends Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "trendIds": [ "example" ], "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "trendIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Suggestions Generate From Trends.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/suggestions/generate-from-trends. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.engagement_feed.list Call GET /api/content-strategy/engagement-feed. Contract: GET /api/content-strategy/engagement-feed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "suggestions": "true" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "suggestions": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Engagement Feed List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/engagement-feed without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.suggestions.get Call GET /api/content-strategy/suggestions/{id}. Contract: GET /api/content-strategy/suggestions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Suggestions Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/suggestions/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.suggestions.update Call PUT /api/content-strategy/suggestions/{id}. Contract: PUT /api/content-strategy/suggestions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "imageUrl": { "type": "string" }, "deferredUntil": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Suggestions Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/content-strategy/suggestions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.suggestions.delete Call DELETE /api/content-strategy/suggestions/{id}. Contract: DELETE /api/content-strategy/suggestions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Suggestions Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/content-strategy/suggestions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.feedback.list Call GET /api/content-strategy/feedback. Contract: GET /api/content-strategy/feedback Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "type": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Feedback List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/content-strategy/feedback without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### content_strategy.feedback.create Call POST /api/content-strategy/feedback. Contract: POST /api/content-strategy/feedback Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "type": "example", "message": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "type", "message" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Feedback Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/content-strategy/feedback. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### content_strategy.feedback.delete Call DELETE /api/content-strategy/feedback/{id}. Contract: DELETE /api/content-strategy/feedback/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Content Strategy Feedback Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/content-strategy/feedback/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.publishing_readiness.get Call GET /api/brands/{id}/publishing-readiness. Contract: GET /api/brands/{id}/publishing-readiness Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "platforms": { "type": "object", "properties": { "x": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "linkedin": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "facebook": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "instagram": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "threads": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "tiktok": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false }, "youtube": { "type": "object", "properties": { "connected": { "type": "boolean" }, "canSchedule": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "account_not_connected", "connection_error", "token_expired", "connection_unavailable" ] } }, "required": [ "connected", "canSchedule" ], "additionalProperties": false } }, "required": [ "x", "linkedin", "facebook", "instagram", "threads", "tiktok", "youtube" ], "additionalProperties": false } }, "required": [ "brandId", "platforms" ], "additionalProperties": false } ``` Effects: Reads provider connection and token readiness without changing state. Verification: Require canSchedule=true for every target platform before scheduling or publishing. Recovery: 404 brand_not_found: Resolve a brand id through brands.list in the same organization before checking publishing readiness. ### brands.voice_context.list Call GET /api/brands/{brandId}/voice-context. Contract: GET /api/brands/{brandId}/voice-context Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "brandId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "brandId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brands Voice Context List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brands/{brandId}/voice-context without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brands.voice_context.create Call POST /api/brands/{brandId}/voice-context. Contract: POST /api/brands/{brandId}/voice-context Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandId": "example", "title": "example", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "title": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "brandId", "title", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brands Voice Context Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/brands/{brandId}/voice-context. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.voice_context.bulk_create Call POST /api/brands/{brandId}/voice-context/bulk. Contract: POST /api/brands/{brandId}/voice-context/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandId": "example", "contexts": [ { "title": "example", "content": "example" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "contexts": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "title": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "title", "content" ], "additionalProperties": false } } }, "required": [ "brandId", "contexts" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brands Voice Context Bulk Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/brands/{brandId}/voice-context/bulk. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.voice_context.retrieve Call POST /api/brands/{brandId}/voice-context/retrieve. Contract: POST /api/brands/{brandId}/voice-context/retrieve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandId": "example", "query": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "query": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] } }, "required": [ "brandId", "query" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brands Voice Context Retrieve.", "additionalProperties": true } ``` Effects: May change state through POST /api/brands/{brandId}/voice-context/retrieve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.voice_context.stats.get Call GET /api/brands/{brandId}/voice-context/stats. Contract: GET /api/brands/{brandId}/voice-context/stats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "brandId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] } }, "required": [ "brandId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brands Voice Context Stats Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/brands/{brandId}/voice-context/stats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brands.voice_context.update Call PUT /api/brands/{brandId}/voice-context/{contextId}. Contract: PUT /api/brands/{brandId}/voice-context/{contextId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandId": "example", "contextId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "contextId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "document", "sample", "guideline", "faq", "competitor", "other" ] }, "title": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "brandId", "contextId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brands Voice Context Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/brands/{brandId}/voice-context/{contextId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brands.voice_context.delete Call DELETE /api/brands/{brandId}/voice-context/{contextId}. Contract: DELETE /api/brands/{brandId}/voice-context/{contextId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "brandId": "example", "contextId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandId": { "type": "string", "minLength": 1 }, "contextId": { "type": "string", "minLength": 1 } }, "required": [ "brandId", "contextId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Brands Voice Context Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/brands/{brandId}/voice-context/{contextId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.usage.get Get AI usage statistics for the selected brand. Contract: GET /api/ai/usage Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/usage without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.usage.history Get AI usage history for the selected brand. Contract: GET /api/ai/usage/history Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "days": { "type": "integer", "minimum": 1, "maximum": 365 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/usage/history without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.usage.limits.get Get AI usage limits for the selected brand. Contract: GET /api/ai/usage/limits Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/usage/limits without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.usage.limits.update Update AI usage limits for the selected brand. Contract: PUT /api/ai/usage/limits Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: accounts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "monthlyTokenLimit": 1, "dailyTokenLimit": 1, "monthlyCostLimitUsd": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "monthlyTokenLimit": { "type": "number", "minimum": 0 }, "dailyTokenLimit": { "type": "number", "minimum": 0 }, "monthlyCostLimitUsd": { "type": "number", "minimum": 0 }, "dailyCostLimitUsd": { "type": "number", "minimum": 0 }, "monthlyRequestLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dailyRequestLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "contentGenerationsPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "trendSearchesPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "imageGenerationsPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "suggestionsPerDay": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "notifyAtPercentage": { "type": "number", "minimum": 0, "maximum": 100 }, "notificationEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "hardLimit": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/ai/usage/limits. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.usage.check Check whether an AI event is within the selected brand limits. Contract: GET /api/ai/usage/check Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "eventType": "content_generation" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventType": { "type": "string", "enum": [ "content_generation", "trend_search", "image_generation", "suggestion", "brand_voice", "strategy_generation" ] } }, "required": [ "eventType" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/usage/check without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.usage.events.list List AI usage events for the selected brand. Contract: GET /api/ai/usage/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "offset": 1, "eventType": "content_generation" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "eventType": { "type": "string", "enum": [ "content_generation", "trend_search", "image_generation", "suggestion", "brand_voice", "strategy_generation" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/usage/events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### seeds.list List shared content-strategy seeds for the selected brand. Contract: GET /api/seeds Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "offset": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/seeds without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### seeds.share Share a content-strategy seed and generate brand suggestions. Contract: POST /api/seeds/share Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: posts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "source": { "platform": "example" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "source": { "type": "object", "properties": { "platform": { "type": "string", "minLength": 1 }, "url": { "type": "string", "format": "uri" }, "sharedText": { "type": "string" }, "sharedAt": { "type": "string" } }, "required": [ "platform" ], "additionalProperties": false }, "targeting": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "one", "selected", "all" ] }, "brandIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false }, "priority": { "type": "string", "enum": [ "urgent", "normal" ] }, "userContext": { "type": "object", "properties": { "note": { "type": "string" } }, "additionalProperties": false } }, "required": [ "source" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/seeds/share. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo Admin source contract Human reference: https://docs.topolo.app/systems/topolo-admin Machine reference: https://docs.topolo.app/machine/systems/topolo-admin.json Source revisions: apps/TopoloAdmin@78b98e22ab49d3ed3bbb72420eeb68d4a4264134 Deploy targets: 2; implemented actions: 1; declared actions: 1; uncatalogued served routes: 0; mobile contracts: 1; route signals: 38. ### widget.get Get the TopoloOne widget summary for Admin. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## Topolo Auth source contract Human reference: https://docs.topolo.app/systems/topolo-auth Machine reference: https://docs.topolo.app/machine/systems/topolo-auth.json Source revisions: topolo-platform/core/TopoloAuth@515376de81efed9734741b2a1d691c8195243073, topolo-platform/packages/topolo-auth-client@515376de81efed9734741b2a1d691c8195243073, topolo-platform/packages/topolo-auth-middleware@515376de81efed9734741b2a1d691c8195243073, topolo-platform/core/TopoloAuth/packages/topolo_auth_flutter@515376de81efed9734741b2a1d691c8195243073 Deploy targets: 1; implemented actions: 181; declared actions: 181; uncatalogued served routes: 4; mobile contracts: 0; route signals: 92. ### organizations.list Read organizations visible to the authenticated Auth principal. Contract: GET /api/organizations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "includeDeleted": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "includeDeleted": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organizations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.get Read organization details by organization id. Contract: GET /api/organizations/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "includeDeleted": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.export Export the portable Auth-owned organization, membership, access, preference, session, and audit record set. Contract: GET /api/organizations/{orgId}/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Export organization identity data.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.billable_seats.get Read the billable seat summary for one organization. Contract: GET /api/organizations/{orgId}/billable-seat-summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization billable seats.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/billable-seat-summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.create Create an organization and optionally invite its first owner. Contract: POST /api/organizations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "ownerEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "ownerName": { "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.update Update one organization. Contract: PATCH /api/organizations/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1 }, "logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "deleted" ] }, "isActive": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/organizations/{orgId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.delete Soft-delete one organization and revoke its active sessions. Contract: DELETE /api/organizations/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete organization.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.delete_permanently Permanently purge Auth-owned data for one soft-deleted organization. Contract: DELETE /api/organizations/{orgId}/permanent Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Permanently delete organization identity data.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/permanent. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.restore Restore one soft-deleted organization. Contract: POST /api/organizations/{orgId}/restore Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Restore organization.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/restore. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.owner_invite.resend Issue a fresh owner invitation for one organization. Contract: POST /api/organizations/{orgId}/resend-owner-invite Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Resend organization owner invite.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/resend-owner-invite. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_principals.list List human and headless principals assignable in one organization. Contract: GET /api/organizations/{orgId}/principals Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization principals.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/principals without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_principals.create Create a headless agent principal accountable to a human organization member. Contract: POST /api/organizations/{orgId}/principals Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "principalType": "agent_employee", "displayName": "example", "accountableUserId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalType": { "type": "string", "const": "agent_employee" }, "displayName": { "type": "string", "minLength": 1 }, "accountableUserId": { "type": "string", "minLength": 1 }, "serviceGrants": { "maxItems": 500, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^[^:]+:.+$" }, { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "scopes": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "appId", "scopes" ], "additionalProperties": false } ] } }, "externalSubjectType": { "type": "string", "minLength": 1 }, "externalSubjectId": { "type": "string", "minLength": 1 }, "templateName": { "type": "string", "minLength": 1 }, "policyRef": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "principalType", "displayName", "accountableUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization principal.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/principals. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_principals.update Update a headless organization principal and its service grants. Contract: PATCH /api/organizations/{orgId}/principals/{principalId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "principalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "suspended", "deleted" ] }, "accountableUserId": { "type": "string", "minLength": 1 }, "serviceGrants": { "maxItems": 500, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^[^:]+:.+$" }, { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "scopes": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "appId", "scopes" ], "additionalProperties": false } ] } }, "policyRef": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "orgId", "principalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization principal.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/organizations/{orgId}/principals/{principalId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### principal_credentials.list List credentials issued to one headless principal. Contract: GET /api/organizations/{orgId}/principals/{principalId}/credentials Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "principalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "principalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List principal credentials.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/principals/{principalId}/credentials without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### principal_credentials.issue Issue a new client credential to one active headless principal. Contract: POST /api/organizations/{orgId}/principals/{principalId}/credentials Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "principalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "orgId", "principalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Issue principal credential.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/principals/{principalId}/credentials. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### principal_credentials.revoke Revoke one headless principal credential. Contract: DELETE /api/organizations/{orgId}/principals/{principalId}/credentials/{credentialId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "principalId": "example", "credentialId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 }, "credentialId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "principalId", "credentialId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke principal credential.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/principals/{principalId}/credentials/{credentialId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_member_roles.assign Assign an additional organization or application role to a member. Contract: POST /api/organizations/{orgId}/members/{userId}/roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "userId": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "userId", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assign organization member role.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/members/{userId}/roles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_member_roles.revoke Revoke an additional organization or application role from a member. Contract: DELETE /api/organizations/{orgId}/members/{userId}/roles/{roleKey} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "userId": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "userId", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke organization member role.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/members/{userId}/roles/{roleKey}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_billing.preview Preview billing for a proposed organization seat quantity. Contract: POST /api/organizations/{orgId}/billing-preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "targetSeatQuantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preview organization billing.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/billing-preview. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_billing.portal.create Create a billing portal session for one organization. Contract: POST /api/organizations/{orgId}/billing-portal Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "returnUrl": { "type": "string", "format": "uri" } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization billing portal session.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/billing-portal. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_onboarding.complete Mark organization-wide onboarding complete for one installed service. Contract: POST /api/organizations/{orgId}/services/{appId}/onboarding-complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete organization service onboarding.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/onboarding-complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### my_service_onboarding.get Read the caller's onboarding progress for one installed service. Contract: GET /api/organizations/{orgId}/services/{appId}/onboarding/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my service onboarding progress.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/onboarding/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_service_onboarding.update Replace the caller's onboarding progress for one installed service. Contract: PUT /api/organizations/{orgId}/services/{appId}/onboarding/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "progress": { "currentStepId": "example", "completedStepIds": [ "example" ], "dismissedStepIds": [ "example" ] } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "progress": { "type": "object", "properties": { "currentStepId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "completedStepIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "dismissedStepIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "dismissedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "required": [ "orgId", "appId", "progress" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update my service onboarding progress.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/services/{appId}/onboarding/me. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### my_service_tours.list List the caller's tour progress for one installed service. Contract: GET /api/organizations/{orgId}/services/{appId}/tours/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my service tour progress.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/tours/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_service_tours.update Replace the caller's progress for one service tour. Contract: PUT /api/organizations/{orgId}/services/{appId}/tours/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "tourId": "example", "progress": { "currentStep": 1, "completed": true, "skipped": true } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "tourId": { "type": "string", "minLength": 1 }, "progress": { "type": "object", "properties": { "currentStep": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completed": { "type": "boolean" }, "skipped": { "type": "boolean" }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "required": [ "orgId", "appId", "tourId", "progress" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update my service tour progress.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/services/{appId}/tours/me. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### households.list List households available to the caller. Contract: GET /api/households Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my households.", "additionalProperties": true } ``` Effects: Reads state through GET /api/households without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### households.create Create a household owned by the caller. Contract: POST /api/households Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create household.", "additionalProperties": true } ``` Effects: May change state through POST /api/households. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### households.get Read one household available to the caller. Contract: GET /api/households/{householdId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get household.", "additionalProperties": true } ``` Effects: Reads state through GET /api/households/{householdId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### households.update Update one household managed by the caller. Contract: PUT /api/households/{householdId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update household.", "additionalProperties": true } ``` Effects: May change state through PUT /api/households/{householdId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### households.delete Delete one household managed by the caller. Contract: DELETE /api/households/{householdId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete household.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/households/{householdId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_members.add Add an existing or invited user to a household. Contract: POST /api/households/{householdId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add household member.", "additionalProperties": true } ``` Effects: May change state through POST /api/households/{householdId}/members. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_members.remove Remove one user from a household. Contract: DELETE /api/households/{householdId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "householdId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "householdId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove household member.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/households/{householdId}/members. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_dependents.add Attach an existing or new dependent to a household. Contract: POST /api/households/{householdId}/dependents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "dependentId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "birthdate": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "relationshipRole": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add household dependent.", "additionalProperties": true } ``` Effects: May change state through POST /api/households/{householdId}/dependents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_dependents.remove Remove one dependent from a household. Contract: DELETE /api/households/{householdId}/dependents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "householdId": "example", "dependentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "dependentId": { "type": "string", "minLength": 1 } }, "required": [ "householdId", "dependentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove household dependent.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/households/{householdId}/dependents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.list List bounded organization-to-application access relationships across the platform. Contract: GET /api/organization-services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization service relationships.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization-services without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_service_relationships.get Read one organization-to-application access relationship. Contract: GET /api/organization-services/{relationshipId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "relationshipId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "relationshipId": { "type": "string", "minLength": 1 } }, "required": [ "relationshipId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization service relationship.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization-services/{relationshipId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_service_relationships.create Grant an organization access to one application. Contract: POST /api/organization-services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "accessLevel": { "type": "string", "enum": [ "basic", "premium", "enterprise", "custom" ] }, "enabled": { "type": "boolean" }, "settings": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "expiresAt": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1 } ] }, { "type": "null" } ] } }, "required": [ "organizationId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization service relationship.", "additionalProperties": true } ``` Effects: May change state through POST /api/organization-services. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.update Update one organization-to-application access relationship. Contract: PUT /api/organization-services/{relationshipId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "relationshipId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "relationshipId": { "type": "string", "minLength": 1 }, "accessLevel": { "type": "string", "enum": [ "basic", "premium", "enterprise", "custom" ] }, "enabled": { "type": "boolean" }, "settings": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "expiresAt": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1 } ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "suspended", "expired" ] } }, "required": [ "relationshipId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization service relationship.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organization-services/{relationshipId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.delete Revoke an organization application relationship. Contract: DELETE /api/organization-services/{relationshipId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "relationshipId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "relationshipId": { "type": "string", "minLength": 1 } }, "required": [ "relationshipId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete organization service relationship.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organization-services/{relationshipId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.check Check one exact organization and application relationship without enumerating the catalog. Contract: GET /api/organization-services/check/{organizationId}/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Check organization service access.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization-services/check/{organizationId}/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_organizations.list List a bounded page of organizations with access to one application. Contract: GET /api/services/{appId}/organizations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service organizations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/organizations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### invitations.list List a bounded page of organization invitations. Contract: GET /api/invitations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example", "page": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List invitations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/invitations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### invitations.create Create an organization invitation and optionally notify its recipient. Contract: POST /api/invitations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example", "email": "user@example.com", "role": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "minLength": 1 }, "expiresInDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 3650 }, "maxUses": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create invitation.", "additionalProperties": true } ``` Effects: May change state through POST /api/invitations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### invitations.delete Delete one organization invitation. Contract: DELETE /api/invitations/{invitationId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "invitationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invitationId": { "type": "string", "minLength": 1 } }, "required": [ "invitationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete invitation.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/invitations/{invitationId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### machine_registry.get Resolve machine launch metadata for one exact accessible application. Contract: GET /api/machine/registry Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 } }, "required": [ "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get machine launch metadata.", "additionalProperties": true } ``` Effects: Reads state through GET /api/machine/registry without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### machine_handoffs.create Create a short-lived handoff for one exact accessible application and launch intent. Contract: POST /api/machine/handoffs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000", "intent": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "intent": { "type": "string", "minLength": 1 }, "target": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "app_id", "intent" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create machine handoff.", "additionalProperties": true } ``` Effects: May change state through POST /api/machine/handoffs. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### my_app_switcher_preferences.get Read the caller's bounded app switcher preferences. Contract: GET /api/app-switcher/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "preferences", "revision", "updatedAt" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Reads the authenticated caller only. Returns the current monotonic preference revision. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_app_switcher_preferences.events List caller-owned preference revisions after an observed revision and return current state. Contract: GET /api/app-switcher/preferences/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "afterRevision": 0, "limit": 50 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "afterRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mutationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "changedKeys": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "favorites", "hidden", "tileSize", "theme", "workspacePins", "widgetDisplay", "chatWidgetState" ] } } }, "required": [ "preferences", "revision", "updatedAt", "mutationId", "changedKeys" ], "additionalProperties": false } }, "state": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "preferences", "revision", "updatedAt" ], "additionalProperties": false } }, "required": [ "events", "state" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Reads the authenticated caller only. Does not consume or delete events. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_app_switcher_preferences.update Update the caller's bounded app switcher preferences. Contract: PUT /api/app-switcher/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "baseRevision": 0, "mutationId": "cli-example-1", "favorites": [ "app_topolo_one" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false }, "baseRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mutationId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "baseRevision", "mutationId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mutationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "changedKeys": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "favorites", "hidden", "tileSize", "theme", "workspacePins", "widgetDisplay", "chatWidgetState" ] } } }, "required": [ "preferences", "revision", "updatedAt", "mutationId", "changedKeys" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Merges only supplied preference fields. Creates one caller-owned revision event. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Retry an ambiguous request with the same mutationId.,On revision conflict, retain local dirty fields and retry against the returned revision. ### my_i18n_preferences.get Resolve the caller's language preferences. Contract: GET /api/i18n/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "00000000-0000-4000-8000-000000000000", "locale": "en-US", "lang": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "lang": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my language preferences.", "additionalProperties": true } ``` Effects: Reads state through GET /api/i18n/preferences without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_i18n_preferences.update Update the caller's language preference. Contract: PUT /api/i18n/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "locale": "en-US", "language": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locale": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update my language preferences.", "additionalProperties": true } ``` Effects: May change state through PUT /api/i18n/preferences. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_preferences.list List notification preferences for the caller or a platform-managed user. Contract: GET /api/users/{userId}/notification-preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "org_id": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user notification preferences.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/notification-preferences without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_preferences.replace Replace the bounded notification preference set for the caller or a platform-managed user. Contract: PUT /api/users/{userId}/notification-preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "rows": [ { "event_type": "system.example", "channel": "email", "enabled": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "query": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "enabled": { "type": "boolean" } }, "required": [ "event_type", "channel", "enabled" ], "additionalProperties": false } } }, "required": [ "userId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace user notification preferences.", "additionalProperties": true } ``` Effects: May change state through PUT /api/users/{userId}/notification-preferences. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_preferences.resolve Resolve effective delivery channels and action policy for one user and event. Contract: GET /api/users/{userId}/notification-preferences/resolve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "user_demo", "org_id": "org_topolo_platform", "event_type": "campaigns.send_completed" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "org_id": { "type": "string", "minLength": 1 }, "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "source_app_id": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "surface": { "type": "string", "enum": [ "notification", "action" ] }, "category": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "priority": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "default_channel": { "anyOf": [ { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp" ] }, { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp" ] } } ] }, "transactional": { "type": "string", "enum": [ "true", "false" ] } }, "required": [ "userId", "org_id", "event_type" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Resolve user notification preferences.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/notification-preferences/resolve without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_channels.list List verified and pending notification addresses for one visible user. Contract: GET /api/users/{userId}/notification-channels Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user notification channels.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/notification-channels without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_channels.create Register a notification address for one visible user. Contract: POST /api/users/{userId}/notification-channels Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "channel": "email", "address": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "whatsapp" ] }, "address": { "type": "string", "minLength": 1 }, "label": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "userId", "channel", "address" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create user notification channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/notification-channels. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_channels.verify Mark one notification address as verified. Contract: POST /api/users/{userId}/notification-channels/{channelId}/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "channelId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Verify user notification channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/notification-channels/{channelId}/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_channels.delete Delete one notification address from a visible user. Contract: DELETE /api/users/{userId}/notification-channels/{channelId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "channelId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user notification channel.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/notification-channels/{channelId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_notification_policy.list List delivery rules enforced by one managed organization. Contract: GET /api/organizations/{orgId}/notification-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization notification policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/notification-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_notification_policy.replace Replace delivery rules enforced by one managed organization. Contract: PUT /api/organizations/{orgId}/notification-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "rows": [ { "event_type": "system.example", "channel": "email", "forbidden": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "forbidden": { "type": "boolean" } }, "required": [ "event_type", "channel", "forbidden" ], "additionalProperties": false } } }, "required": [ "orgId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace organization notification policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/notification-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_notification_action_policy.list List action-delivery policy rules for one managed organization. Contract: GET /api/organizations/{orgId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization notification action policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/notification-action-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_notification_action_policy.replace Replace action-delivery policy rules for one managed organization. Contract: PUT /api/organizations/{orgId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "rows": [ { "delivery_mode": "immediate", "required_action": true, "enabled": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "source_app_id": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "surface": { "type": "string", "enum": [ "notification", "action", "*" ] }, "category": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "priority": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "delivery_mode": { "type": "string", "enum": [ "immediate", "digest", "in_app_only", "muted" ] }, "required_action": { "type": "boolean" }, "quiet_hours": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "digest": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "escalation": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "enabled": { "type": "boolean" } }, "required": [ "delivery_mode", "required_action", "enabled" ], "additionalProperties": false } } }, "required": [ "orgId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace organization notification action policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/notification-action-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_action_policy.list List action-delivery policy rules for the caller or a user in a managed organization. Contract: GET /api/organizations/{orgId}/users/{userId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user notification action policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/users/{userId}/notification-action-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_action_policy.replace Replace action-delivery policy rules for the caller or a user in a managed organization. Contract: PUT /api/organizations/{orgId}/users/{userId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "userId": "example", "rows": [ { "delivery_mode": "immediate", "required_action": true, "enabled": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "source_app_id": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "surface": { "type": "string", "enum": [ "notification", "action", "*" ] }, "category": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "priority": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "delivery_mode": { "type": "string", "enum": [ "immediate", "digest", "in_app_only", "muted" ] }, "required_action": { "type": "boolean" }, "quiet_hours": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "digest": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "escalation": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "enabled": { "type": "boolean" } }, "required": [ "delivery_mode", "required_action", "enabled" ], "additionalProperties": false } } }, "required": [ "orgId", "userId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace user notification action policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/users/{userId}/notification-action-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_connected_apps.list List developer OAuth applications currently connected to the caller. Contract: GET /api/developer-oauth/connected-apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my connected OAuth apps.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-oauth/connected-apps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### developer_oauth_connected_apps.disconnect Revoke the caller's refresh tokens for one connected OAuth client. Contract: DELETE /api/developer-oauth/connected-apps/{clientId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "clientId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1 } }, "required": [ "clientId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Disconnect OAuth app.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-oauth/connected-apps/{clientId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_clients.list List OAuth clients owned by the caller's developer organization. Contract: GET /api/developer-oauth/clients Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List developer OAuth clients.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-oauth/clients without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### developer_oauth_clients.create Create an OAuth client for the caller's developer organization and return its secret once when confidential. Contract: POST /api/developer-oauth/clients Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "developer_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "developer_id": { "type": "string", "minLength": 1 }, "developer_app_id": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "client_type": { "type": "string", "enum": [ "public", "confidential" ] }, "grant_types": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirect_uris": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowed_scopes": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "homepage_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "name", "developer_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create developer OAuth client.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-oauth/clients. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_clients.rotate_secret Rotate and return the secret for one confidential OAuth client. Contract: POST /api/developer-oauth/clients/{id}/rotate-secret Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Rotate developer OAuth client secret.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-oauth/clients/{id}/rotate-secret. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_clients.revoke Revoke one OAuth client and all of its active refresh tokens. Contract: DELETE /api/developer-oauth/clients/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke developer OAuth client.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-oauth/clients/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_config.get Read merged login branding and active event config for one application. Contract: GET /api/login-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get application login config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-config/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### login_config.update Update only the supplied login config fields for one application. Contract: PUT /api/login-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "logo_dark_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "features": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "allowed_providers": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "authenticated_home_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "magic_link_delivery_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_avatar_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "enable_cursor_effects": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "enable_mini_games": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "mini_game_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_css": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_head_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "copyright_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update application login config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/login-config/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### master_login_config.get Read the platform-wide default login branding config. Contract: GET /api/login-config-master Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get master login config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-config-master without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### master_login_config.update Update only the supplied platform-wide default login fields. Contract: PUT /api/login-config-master Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brand_name": "example", "brand_tagline": "example", "brand_logo_url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand_tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand_logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "brand_logo_dark_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "default_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "enable_cursor_effects": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "enable_mini_games": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "mini_game_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "show_social_links": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "social_links": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update master login config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/login-config-master. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### landing_config.get Read the app-specific landing presentation, returning-user login action, and policy-controlled signup journey for one application. Contract: GET /api/landing-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get application landing config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/landing-config/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### landing_config.update Create or update supplied landing-page fields for one application. Contract: PUT /api/landing-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_cta_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_cta_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "hero_badge_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_cta_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_cta_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "features": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "stats": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "integrations": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "testimonial_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_avatar_initials": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "problem_statement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "solution_statement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "cta_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cta_subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pricing_enabled": { "type": "boolean" }, "pricing_tiers": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "footer_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer_links": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "legal_links": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "show_topolo_one": { "type": "boolean" }, "is_enabled": { "type": "boolean" } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update application landing config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/landing-config/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### app_ui_config.get Read shared authenticated-shell colors and notes for one application. Contract: GET /api/app-ui-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get application UI config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/app-ui-config/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### app_ui_config.update Update only supplied authenticated-shell fields for one application. Contract: PUT /api/app-ui-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "highlight_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highlight_color_dark": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hint_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hint_color_dark": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update application UI config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/app-ui-config/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_events.list List a bounded page of scheduled login themes. Contract: GET /api/login-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "cursor": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "cursor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List login events.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### login_events.create Create a scheduled login theme for selected applications or the platform. Contract: POST /api/login-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "app_ids": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "null" } ] }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlay_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "lottie_animation_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "event_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "special_interaction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interaction_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create login event.", "additionalProperties": true } ``` Effects: May change state through POST /api/login-events. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_events.update Update supplied fields on one scheduled login theme. Contract: PUT /api/login-events/{eventId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "eventId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "app_ids": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "null" } ] }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlay_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "lottie_animation_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "event_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "special_interaction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interaction_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "eventId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update login event.", "additionalProperties": true } ``` Effects: May change state through PUT /api/login-events/{eventId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_events.delete Delete one scheduled login theme. Contract: DELETE /api/login-events/{eventId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "eventId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1 } }, "required": [ "eventId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete login event.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/login-events/{eventId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_presets.list List a bounded page of reusable login theme presets. Contract: GET /api/login-presets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "cursor": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "cursor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List login presets.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-presets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### login_presets.create Create a reusable login theme preset. Contract: POST /api/login-presets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "config": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "category": { "type": "string", "minLength": 1 }, "tags": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "string" } ] } }, "required": [ "name", "config" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create login preset.", "additionalProperties": true } ``` Effects: May change state through POST /api/login-presets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_presets.delete Delete one non-system login theme preset. Contract: DELETE /api/login-presets/{presetId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "presetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presetId": { "type": "string", "minLength": 1 } }, "required": [ "presetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete login preset.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/login-presets/{presetId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### platform_pricing.get Read the platform-wide pricing configuration. Contract: GET /api/admin/platform-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get platform pricing.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/platform-pricing without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### platform_pricing.update Update the platform-wide pricing configuration. Contract: PUT /api/admin/platform-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "base": { "planId": "example", "monthlyCentsPerSeat": 1 }, "includedFreeInBase": [ { "appId": "example", "headline": "example" } ], "platformCapabilities": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "base": { "type": "object", "properties": { "planId": { "type": "string", "minLength": 1 }, "monthlyCentsPerSeat": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "minimumSeats": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "seatTiers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo", "unitAmountCents" ], "additionalProperties": false } } }, "required": [ "planId", "monthlyCentsPerSeat" ], "additionalProperties": false }, "includedFreeInBase": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "headline": { "type": "string", "minLength": 1 }, "marketingPath": { "type": "string", "minLength": 1 } }, "required": [ "appId", "headline" ], "additionalProperties": false } }, "platformCapabilities": { "maxItems": 1000, "type": "array", "items": { "type": "string" } }, "platformTagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schemaVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update platform pricing.", "additionalProperties": true } ``` Effects: May change state through PUT /api/admin/platform-pricing. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### app_pricing_plans.list List pricing plans registered for one application. Contract: GET /api/admin/pricing-plans/by-app/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List application pricing plans.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/pricing-plans/by-app/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### app_pricing_plans.bulk_register Create or update a bounded set of application pricing plans. Contract: POST /api/admin/pricing-plans/bulk-register Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "plans": [ { "id": "demo_monthly", "displayName": "Demo Monthly", "pricingModel": "flat" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "plans": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "appId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "developerOrgId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1 }, "pricingModel": { "type": "string", "enum": [ "free", "included", "flat", "per_seat", "per_seat_tiered", "metered", "metered_tiered", "flat_plus_metered", "one_time" ] }, "unitLabel": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "billingCurrency": { "type": "string", "minLength": 1 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "day", "week", "month", "year" ] }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "revShareBps": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "pricingDetails": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tiers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo" ], "additionalProperties": false } }, "tiersMode": { "type": "string", "enum": [ "graduated", "volume" ] }, "meteredUnitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatBaseAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "id", "displayName", "pricingModel" ], "additionalProperties": false } } }, "required": [ "plans" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk register application pricing plans.", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/pricing-plans/bulk-register. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### app_pricing_meters.register Create or update application usage meters and plan quotas. Contract: POST /api/admin/billing/register-app-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "meters": [ { "key": "example", "displayName": "example", "unit": "example" } ], "quotas": [ { "pricingPlanId": "example", "meterKey": "example", "includedPerSeat": 1, "includedFlat": 1 } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "meters": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "unit": { "type": "string", "minLength": 1 }, "billPerN": { "type": "number", "exclusiveMinimum": 0 }, "ttuMultipliers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number", "exclusiveMinimum": 0 } } }, "required": [ "key", "displayName", "unit" ], "additionalProperties": false } }, "quotas": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "pricingPlanId": { "type": "string", "minLength": 1 }, "meterKey": { "type": "string", "minLength": 1 }, "includedPerSeat": { "type": "number", "minimum": 0 }, "includedFlat": { "type": "number", "minimum": 0 }, "overagePriceId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultHardCapMultiplier": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "pricingPlanId", "meterKey", "includedPerSeat", "includedFlat" ], "additionalProperties": false } } }, "required": [ "appId", "meters", "quotas" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Register application pricing meters.", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/billing/register-app-pricing. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### resource_grants.list_mine List a bounded page of the caller's live resource grants. Contract: GET /api/resource-grants/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "00000000-0000-4000-8000-000000000000", "app_id": "00000000-0000-4000-8000-000000000000", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "cursor": { "type": "string", "pattern": "^\\d+:[A-Za-z0-9_-]+$" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my resource grants.", "additionalProperties": true } ``` Effects: Reads state through GET /api/resource-grants/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### resource_grants.create Grant a user access to one application resource when the caller can manage the organization or target application grants. Contract: POST /api/resource-grants Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example", "appId": "example", "resourceType": "example", "resourceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "minLength": 1 }, "grantType": { "type": "string", "minLength": 1 }, "expiresAt": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "organizationId", "appId", "resourceType", "resourceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create resource grant.", "additionalProperties": true } ``` Effects: May change state through POST /api/resource-grants. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### resource_grants.revoke Revoke one resource grant when the caller can manage its organization. Contract: POST /api/resource-grants/{grantId}/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "grantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grantId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "grantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke resource grant.", "additionalProperties": true } ``` Effects: May change state through POST /api/resource-grants/{grantId}/revoke. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### resource_grants.promote Promote a scoped user to an organization member when the caller can manage the organization or target application grants. Contract: POST /api/resource-grants/promote Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Promote resource-grant user.", "additionalProperties": true } ``` Effects: May change state through POST /api/resource-grants/promote. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.list List active canonical workspaces the caller may use in one application and organization. Contract: GET /api/workspaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "org_acme", "app_id": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "org_id", "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List workspaces.", "additionalProperties": true } ``` Effects: Reads canonical workspace identity, ownership, access, and default state from Topolo Auth. Verification: Use only workspace ids returned for the requested app_id and org_id. Confirm exactly one active workspace is marked as the application default. Recovery: Refresh the active organization and application context before retrying discovery. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. ### workspaces.create Create one canonical workspace for an application and organization. Contract: POST /api/workspaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "org_acme", "appId": "app_topolo_campaigns", "name": "Launch operations" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "isDefault": { "type": "boolean" } }, "required": [ "organizationId", "appId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create workspace.", "additionalProperties": true } ``` Effects: Creates canonical workspace identity in Topolo Auth. Makes the first active workspace the default, or honors isDefault when explicitly requested. Verification: Run workspaces.list for the same application and organization and confirm the new id appears once. Confirm the returned stable slug is not reused as the display name. Recovery: Refresh workspace discovery before retrying so a successful response is not duplicated after a network timeout. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. ### workspaces.rename Rename canonical workspace presentation without changing its stable id or slug. Contract: PATCH /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "name": "Customer launch" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "workspaceId", "organizationId", "appId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Rename workspace.", "additionalProperties": true } ``` Effects: Changes only the canonical display name. Preserves the workspace id, slug, ownership, membership, and application data. Verification: Run workspaces.list and confirm the new name is returned for the same workspace id. Confirm app-local resources remain scoped to the unchanged workspace id. Recovery: Rediscover the workspace before retrying if ownership or organization context changed. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. ### workspaces.default.set Set the single canonical default workspace for an application and organization. Contract: PUT /api/workspaces/{workspaceId}/default Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "organizationId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set default workspace.", "additionalProperties": true } ``` Effects: Atomically makes this the only active default workspace for the application and organization. Verification: Run workspaces.list and confirm exactly this workspace is marked as default. Recovery: Do not infer default state after a conflict; rediscover it from Topolo Auth. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. 409 CONFLICT: Refresh canonical workspace state and retry only if this workspace should still become the default. ### workspace_access.list_mine List active workspaces the caller may access in one application and organization. Contract: GET /api/workspace-access/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "org_acme", "app_id": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "org_id", "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List accessible workspaces.", "additionalProperties": true } ``` Effects: Reads the caller-specific workspace projection without changing access. Verification: Confirm data.accessMode is all only for organization owner, super admin, or platform break-glass authority. Use only resource ids returned in data.resources for subsequent workspace-scoped actions. Recovery: Refresh the active organization context and repeat discovery before retrying a denied workspace action. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_access.members.list List the owner, explicit members, and eligible same-organization assignees for one workspace. Contract: GET /api/workspace-access/{resourceId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "resourceId": "workspace_123", "org_id": "org_acme", "app_id": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "resourceId", "org_id", "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List workspace members.", "additionalProperties": true } ``` Effects: Reads workspace ownership, member grants, and assignable same-organization users. Verification: Confirm data.owner.accessRole is owner and no data.members entry is marked owner. Select grant and transfer targets only from data.assignableUsers or data.members. Recovery: Run workspace_access.list_mine and retry with a currently accessible workspace. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_access.members.grant Grant an active same-organization app member access to one workspace. Contract: POST /api/workspace-access/{resourceId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "resourceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "userId": "usr_member", "scope": "read_write" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "read", "read_write", "admin" ] } }, "required": [ "resourceId", "organizationId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Grant workspace access.", "additionalProperties": true } ``` Effects: Creates or reactivates one workspace member grant. Does not create organization membership, app entitlement, a seat, or ownership. Verification: Run workspace_access.members.list and confirm the target user appears once in data.members. Validate a workspace-scoped request as the target user before treating access as complete. Recovery: Confirm the target already belongs to the organization and has app access, then retry without provisioning a new identity. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_access.members.revoke Revoke one explicit workspace member grant without changing organization membership. Contract: POST /api/workspace-access/{resourceId}/members/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "resourceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "userId": "usr_member", "reason": "Campaign complete" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "resourceId", "organizationId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke workspace access.", "additionalProperties": true } ``` Effects: Revokes the target user explicit access to this workspace. Does not remove organization membership, app entitlement, a seat, or access to other workspaces. Verification: Run workspace_access.members.list and confirm the target is absent from data.members. Confirm a workspace-scoped request by the target is denied unless they hold an organization-wide override. Recovery: If the user is the current owner, transfer ownership first; owner access cannot be revoked as a member grant. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_ownership.transfer Atomically transfer the single primary owner role to an active same-organization app member. Contract: POST /api/workspace-access/{resourceId}/transfer Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "resourceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "newOwnerUserId": "usr_new_owner", "retainPreviousOwnerAccess": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "newOwnerUserId": { "type": "string", "minLength": 1 }, "retainPreviousOwnerAccess": { "type": "boolean" } }, "required": [ "resourceId", "organizationId", "appId", "newOwnerUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Transfer workspace ownership.", "additionalProperties": true } ``` Effects: Replaces the single workspace owner in one atomic update. Removes any redundant member grant for the new owner. Retains the previous owner as an admin-scoped member unless retainPreviousOwnerAccess is false. Verification: Run workspace_access.members.list and confirm the new owner is data.owner. Confirm exactly one owner and check whether the previous owner remains in data.members as requested. Recovery: Do not retry blindly after a conflict; rediscover the current owner and require a fresh transfer decision. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. 409 CONFLICT: Refresh workspace members because ownership changed, then retry only if the transfer is still intended. ### me.get Read the caller's current Auth identity, context, and optional service permissions. Contract: GET /api/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my Auth profile.", "additionalProperties": true } ``` Effects: Reads state through GET /api/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### me.tenant.get Read the organization selected by the caller's credential-bound context. Contract: GET /api/tenant Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my organization.", "additionalProperties": true } ``` Effects: Reads state through GET /api/tenant without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### me.recovery_email.get Read the caller's personal recovery email status. Contract: GET /api/me/recovery-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my recovery email.", "additionalProperties": true } ``` Effects: Reads state through GET /api/me/recovery-email without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### me.recovery_email.request_verification Set the caller's personal recovery email and send a verification request. Contract: POST /api/me/recovery-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "email": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Request recovery email verification.", "additionalProperties": true } ``` Effects: May change state through POST /api/me/recovery-email. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### me.sessions.revoke_all Revoke every access token, refresh token, and session belonging to the caller. Contract: POST /api/auth/logout-everywhere Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke all my sessions.", "additionalProperties": true } ``` Effects: May change state through POST /api/auth/logout-everywhere. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.list Read users visible to the authenticated Auth principal. Contract: GET /api/users Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List users.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### users.get Read one user and their visible security state. Contract: GET /api/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### users.export Export the portable Auth-owned identity, access, preference, session, and audit record set for one user. Contract: GET /api/users/{userId}/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Export user identity data.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_users.list List users in one organization, including deleted organizations when explicitly requested. Contract: GET /api/users/organization/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "includeDeletedOrganizations": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization users.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/organization/{orgId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### users.create Create a user in an organization managed by the caller. Contract: POST /api/users Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "email": "user@example.com", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "orgId": { "type": "string", "minLength": 1 }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "password": { "type": "string", "minLength": 8 } }, "required": [ "email", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create user.", "additionalProperties": true } ``` Effects: May change state through POST /api/users. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.update Update one user profile or organization role. Contract: PUT /api/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update user.", "additionalProperties": true } ``` Effects: May change state through PUT /api/users/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.status.update Activate or suspend one user. Contract: PATCH /api/users/{userId}/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "isActive": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" } }, "required": [ "userId", "isActive" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update user status.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/users/{userId}/status. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.delete Soft-delete one user, revoke their sessions, and release their email address. Contract: DELETE /api/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.delete_permanently Permanently purge Auth-owned data for one deleted user. Contract: DELETE /api/users/{userId}/permanent Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Permanently delete user.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/permanent. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_permissions.get Evaluate one user's effective permissions, optionally for one service. Contract: GET /api/users/{userId}/permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "service": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/permissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_permission_overrides.list List explicit allow and deny overrides for one user. Contract: GET /api/users/{userId}/service-permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user permission overrides.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/service-permissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_permission_overrides.create Create an explicit service permission allow or deny override for one user. Contract: POST /api/users/{userId}/service-permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "orgId": "example", "appId": "example", "permissionName": "example", "effect": "allow" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "permissionName": { "type": "string", "minLength": 1 }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "userId", "orgId", "appId", "permissionName", "effect" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create user permission override.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/service-permissions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_permission_overrides.delete Delete one explicit user permission override. Contract: DELETE /api/users/{userId}/service-permissions/{overrideId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "overrideId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "overrideId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "overrideId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user permission override.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/service-permissions/{overrideId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_service_access.get Read one user's effective application access and seat assignments. Contract: GET /api/users/{userId}/service-access Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "appSwitcherOnly": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user service access.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/service-access without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_service_access.replace Replace one user's assigned applications across organization-enabled services. Contract: PUT /api/users/{userId}/service-access Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "appIds": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "appSwitcherOnly": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] }, "appIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "userId", "appIds" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace user service access.", "additionalProperties": true } ``` Effects: May change state through PUT /api/users/{userId}/service-access. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sessions.list Read sessions for the caller or a managed user. Contract: GET /api/users/{userId}/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user sessions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/sessions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sessions.delete Revoke one session belonging to the caller or a managed user. Contract: DELETE /api/users/{userId}/sessions/{sessionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user session.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/sessions/{sessionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_oauth_providers.list List external sign-in providers linked to one visible user. Contract: GET /api/users/{userId}/oauth-providers Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user OAuth providers.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/oauth-providers without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_oauth_providers.unlink Unlink one external sign-in provider from a visible user. Contract: DELETE /api/users/{userId}/oauth-providers/{provider} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "provider": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 } }, "required": [ "userId", "provider" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Unlink user OAuth provider.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/oauth-providers/{provider}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.unlock Clear the failed-login lockout for one managed user. Contract: POST /api/users/{userId}/unlock Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Unlock user account.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/unlock. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.mfa_protection.canary Verify that every retained MFA secret is protected and every backup code is hash-only. Contract: GET /api/admin/privacy/mfa-protection/canary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Check Auth MFA protection.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/privacy/mfa-protection/canary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_security.get Read MFA, passkey, backup-code, and account-lock status for one visible user. Contract: GET /api/users/{userId}/2fa-status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user security status.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/2fa-status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_mfa.setup Create a time-limited MFA setup secret, QR code, backup codes, and verification token. Contract: POST /api/users/{userId}/mfa/setup Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Begin user MFA setup.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/mfa/setup. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_mfa.verify Verify a TOTP code and enable MFA for one user. Contract: POST /api/users/{userId}/mfa/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "token": "example", "setupToken": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "setupToken": { "type": "string", "minLength": 1 } }, "required": [ "userId", "token", "setupToken" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Verify user MFA setup.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/mfa/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_mfa.disable Disable MFA for one visible user. Contract: DELETE /api/users/{userId}/mfa Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Disable user MFA.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/mfa. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_mfa.backup_codes.regenerate Replace and return the one-time backup codes for an MFA-enabled user. Contract: POST /api/users/{userId}/backup-codes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Regenerate user backup codes.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/backup-codes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_passkeys.registration.begin Create WebAuthn registration options for one user. Contract: POST /api/users/{userId}/passkeys/setup Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Begin passkey registration.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/passkeys/setup. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_passkeys.registration.complete Verify and store a WebAuthn credential for one user. Contract: POST /api/users/{userId}/passkeys/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "credential": {}, "challengeId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "credential": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "challengeId": { "type": "string", "minLength": 1 }, "friendlyName": { "type": "string", "minLength": 1 } }, "required": [ "userId", "credential", "challengeId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete passkey registration.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/passkeys/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_passkeys.list List sanitized passkey credentials for one visible user. Contract: GET /api/users/{userId}/passkeys Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user passkeys.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/passkeys without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_passkeys.delete Delete one passkey credential belonging to a visible user. Contract: DELETE /api/users/{userId}/passkeys/{passkeyId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "passkeyId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "passkeyId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "passkeyId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user passkey.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/passkeys/{passkeyId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_password.change Change the caller's password after verifying their current password. Contract: POST /api/users/{userId}/password Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "currentPassword": "examplex", "newPassword": "examplex" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "currentPassword": { "type": "string", "minLength": 8 }, "newPassword": { "type": "string", "minLength": 8 } }, "required": [ "userId", "currentPassword", "newPassword" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Change my password.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/password. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_password.set_initial Establish the caller's first password for a passwordless account. Contract: POST /api/users/{userId}/password/initial Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "newPassword": "examplex" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "newPassword": { "type": "string", "minLength": 8 } }, "required": [ "userId", "newPassword" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set my initial password.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/password/initial. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_password.admin_reset Set a new password for one user managed by the caller. Contract: POST /api/users/{userId}/password/admin-reset Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "newPassword": "examplex" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "newPassword": { "type": "string", "minLength": 8 } }, "required": [ "userId", "newPassword" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reset user password.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/password/admin-reset. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### api_keys.options List the applications scopes and resources the caller may bind to a new API key. Contract: GET /api/api-keys/options Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "minLength": 1 }, "data": { "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "canCreate": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "app_id", "name" ], "additionalProperties": {} } }, "organizationWideScopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "app_id", "name" ], "additionalProperties": {} } }, "resourceTypes": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "emptyLabel": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "label", "emptyLabel" ], "additionalProperties": {} } }, "resources": { "type": "array", "items": { "type": "object", "properties": { "resource_type": { "type": "string", "minLength": 1 }, "resource_id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "accessLevel": { "type": "string", "minLength": 1 }, "allowedScopes": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "resource_type", "resource_id", "label", "status", "accessLevel", "allowedScopes" ], "additionalProperties": {} } } }, "required": [ "organizationId", "appId", "serviceName", "canCreate", "scopes", "organizationWideScopes", "resourceTypes", "resources" ], "additionalProperties": false }, "timestamp": { "type": "string", "minLength": 1 } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Returns only applications scopes and resources currently available to the authenticated caller. Verification: Use the returned allowedScopes without widening them before planning api_keys.create. Recovery: 400 VALIDATION_ERROR: Correct the application or organization identifier and retry. 403 FORBIDDEN: Use an application and organization visible to the authenticated caller. ### api_keys.list List central API keys visible to the caller. Contract: GET /api/api-keys Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List API keys.", "additionalProperties": true } ``` Effects: Reads state through GET /api/api-keys without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### api_keys.create Create a credential scoped to one organization, application, permission set, and optional resources. Contract: POST /api/api-keys Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_campaigns", "name": "Staging demo agent", "scopes": [ "workspaces:read" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "scopes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, "resourceBindings": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "resourceId" ], "additionalProperties": false } }, "expiresInDays": { "type": "number", "minimum": 0 } }, "required": [ "appId", "name", "scopes" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "minLength": 1 }, "data": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "organizationSlug": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "scopes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, "resourceBindings": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "resourceId" ], "additionalProperties": false } }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "active" }, "secret": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "organizationId", "organizationSlug", "appId", "scopes", "resourceBindings", "expiresAt", "createdAt", "status", "secret" ], "additionalProperties": false } }, "required": [ "key" ], "additionalProperties": false }, "timestamp": { "type": "string", "minLength": 1 } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Creates one API key for the requested application, scopes, and resource bindings. Returns the plaintext API key secret exactly once in data.key.secret. Verification: Store data.key.secret in the intended secret manager because it cannot be retrieved again. Inject the secret as TOPOLO_API_KEY in an isolated process and run topolo whoami --json. Run topolo resources for data.key.appId and confirm only the intended resource bindings are returned. Recovery: 400 VALIDATION_ERROR: Correct the reported field using the published input schema and retry. 403 FORBIDDEN: Use an authorized organization, application, scope, and resource selection; do not widen access automatically. 500 SERVER_ERROR: Preserve the request id and retry only after the platform error is resolved. ### api_keys.update Update the name, scopes, resource bindings, or expiry of one API key. Contract: PUT /api/api-keys/{apiKeyId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "apiKeyId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "apiKeyId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "scopes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, "resourceBindings": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "resourceId" ], "additionalProperties": false } }, "expiresInDays": { "type": "number", "minimum": 0 } }, "required": [ "apiKeyId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update API key.", "additionalProperties": true } ``` Effects: May change state through PUT /api/api-keys/{apiKeyId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### api_keys.revoke Revoke one central API key. Contract: POST /api/api-keys/{apiKeyId}/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "apiKeyId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "apiKeyId": { "type": "string", "minLength": 1 } }, "required": [ "apiKeyId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke API key.", "additionalProperties": true } ``` Effects: May change state through POST /api/api-keys/{apiKeyId}/revoke. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sso_exchange_diagnostics.list Inspect sanitized handoff-to-exchange timing, replay outcomes, failures, and request correlation within the caller-visible organization. Contract: GET /api/sso/exchange-diagnostics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "org_acme", "requestId": "3f9c867d-0c1e-4ec7-9aaf-8f74be533b61", "limit": 25 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 }, "outcome": { "type": "string", "enum": [ "pending", "redeemed", "replayed", "denied", "failed" ] }, "since": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "until": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "exchanges": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "exchangeId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "appId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirectOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "codeExpiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstExchangeAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastExchangeAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "firstRequestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastRequestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exchangeAttemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "replayCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "pending", "redeemed", "replayed", "denied", "failed" ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handoffToFirstExchangeMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "exchangeId", "userId", "appId", "organizationId", "redirectOrigin", "createdAt", "codeExpiresAt", "firstExchangeAt", "lastExchangeAt", "firstRequestId", "lastRequestId", "exchangeAttemptCount", "replayCount", "outcome", "errorCode", "handoffToFirstExchangeMs", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "exchanges", "total", "limit", "offset" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Reads a seven-day sanitized exchange diagnostic ledger without returning codes, hashes, tokens, redirect paths, or cached user payloads. Verification: Confirm every returned organizationId matches the requested organization or the caller active organization. When requestId is supplied, confirm it equals each row firstRequestId or lastRequestId. Use createdAt, firstExchangeAt, lastExchangeAt, handoffToFirstExchangeMs, outcome, and errorCode together when diagnosing exchange timing or failure. Recovery: Narrow by organization, application, request ID, outcome, or time window; diagnostics older than seven days are intentionally unavailable. 400 VALIDATION_ERROR: Correct the closed filter schema or time range and retry. 401 AUTH_ERROR: Refresh the caller session or credential before retrying. 403 FORBIDDEN: Use sessions:read within the active organization; do not widen the requested tenant. ### admin.stats Read Auth admin dashboard statistics. Contract: GET /api/admin/stats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get Auth admin stats.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/stats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.system_health Read Auth system health status. Contract: GET /api/admin/system-health Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "cursor": "app_topolo_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "cursor": { "type": "string", "pattern": "^app_[a-z0-9]+(?:_[a-z0-9]+)+$" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get Auth system health.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/system-health without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### audit_logs.list Read Auth audit log entries. Contract: GET /api/audit-logs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "action": "example", "organization": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "minLength": 1 }, "organization": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List audit logs.", "additionalProperties": true } ``` Effects: Reads state through GET /api/audit-logs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.recent_activity Read recent activity recorded by the Auth control plane. Contract: GET /api/admin/recent-activity Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get recent Auth activity.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/recent-activity without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### services.list List services registered with the Auth control plane. Contract: GET /api/services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "cursor": "app_topolo_example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "pattern": "^app_[a-z0-9]+(?:_[a-z0-9]+)+$" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List services.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### services.get Read one registered service by canonical application id. Contract: GET /api/services/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get service.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### services.create Create a platform-managed service registration. Contract: POST /api/services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "base_url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "base_url": { "type": "string", "format": "uri" }, "version": { "type": "string", "minLength": 1 }, "api_key_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "show_in_app_switcher": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "name", "base_url" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create service.", "additionalProperties": true } ``` Effects: May change state through POST /api/services. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### services.update Update a platform-managed service registration. Contract: PUT /api/services/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "base_url": { "type": "string", "format": "uri" }, "version": { "type": "string", "minLength": 1 }, "api_key_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "status": { "type": "string", "enum": [ "active", "inactive", "deleted" ] }, "show_in_app_switcher": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update service.", "additionalProperties": true } ``` Effects: May change state through PUT /api/services/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### services.delete Delete a platform-managed service registration. Contract: DELETE /api/services/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete service.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/services/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_permissions.list List permissions declared by one service. Contract: GET /api/services/{appId}/permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/permissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_api_key_scopes.list List API key scopes exposed by one service. Contract: GET /api/services/{appId}/api-key-scopes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service API key scopes.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/api-key-scopes without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_api_key_resources.list List credential-bindable resources exposed by one service. Contract: GET /api/services/{appId}/api-key-resources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service API key resources.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/api-key-resources without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_permissions.create Create a permission for one platform-managed service. Contract: POST /api/services/{appId}/permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "name": "2026-01-01" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9:_-]+$" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "appId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create service permission.", "additionalProperties": true } ``` Effects: May change state through POST /api/services/{appId}/permissions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_permissions.update Update one service permission. Contract: PUT /api/permissions/{permissionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "permissionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "permissionId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9:_-]+$" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "permissionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update service permission.", "additionalProperties": true } ``` Effects: May change state through PUT /api/permissions/{permissionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_permissions.delete Delete one service permission. Contract: DELETE /api/permissions/{permissionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "permissionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "permissionId": { "type": "string", "minLength": 1 } }, "required": [ "permissionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete service permission.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/permissions/{permissionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_role_permissions.get Read a service role permission bundle. Contract: GET /api/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example", "role": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 } }, "required": [ "appId", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get service role permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/role-permissions/{role} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_role_permissions.replace Replace the permission bundle for a service role. Contract: PUT /api/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "role": "example", "permissions": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permissions": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "appId", "role", "permissions" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace service role permissions.", "additionalProperties": true } ``` Effects: May change state through PUT /api/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_role_permissions.add Add one permission to a service role. Contract: POST /api/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add service role permission.", "additionalProperties": true } ``` Effects: May change state through POST /api/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_role_permissions.remove Remove one permission from a service role. Contract: DELETE /api/services/{appId}/role-permissions/{role}/{permission} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove service role permission.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/services/{appId}/role-permissions/{role}/{permission}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_roles.list List the operator roles declared by one service. Contract: GET /api/services/{appId}/declared-roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List declared service roles.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/declared-roles without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_roles.list List roles defined for one organization. Contract: GET /api/organizations/{orgId}/roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization roles.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/roles without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_roles.create Create a custom role for one organization. Contract: POST /api/organizations/{orgId}/roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] }, "templateRoleKey": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization role.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/roles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_roles.delete Delete one custom organization role. Contract: DELETE /api/organizations/{orgId}/roles/{roleKey} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete organization role.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/roles/{roleKey}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_services.install Install or update access to an application for one organization. Contract: POST /api/organizations/{orgId}/services/{appId}/install Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "enum": [ "everyone", "me", "users" ] }, "userIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "user_ids": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Install organization service.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/install. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_seats.get Read seat pools and usage across an organization. Contract: GET /api/organizations/{orgId}/seats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization seat summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/seats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_seats.get Read one service seat pool and its assignees. Contract: GET /api/organizations/{orgId}/services/{appId}/seats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get service seats.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/seats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_seats.assign Assign an application seat to an organization member. Contract: POST /api/organizations/{orgId}/services/{appId}/seats/assign Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assign service seat.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/seats/assign. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_seats.revoke Revoke an application seat from an organization member. Contract: POST /api/organizations/{orgId}/services/{appId}/seats/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke service seat.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/seats/revoke. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_seats.reseat Move an application seat between organization members. Contract: POST /api/organizations/{orgId}/services/{appId}/seats/reseat Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "fromUserId": "example", "toUserId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "fromUserId": { "type": "string", "minLength": 1 }, "toUserId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "fromUserId", "toUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reassign service seat.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/seats/reseat. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_services.request_access Request access to an application from organization administrators. Contract: POST /api/organizations/{orgId}/services/{appId}/access-request Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "maxLength": 500 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Request service access.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/access-request. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_role_permissions.get Read one organization role permission bundle for an application. Contract: GET /api/organizations/{orgId}/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example", "role": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization role permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/role-permissions/{role} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_role_permissions.replace Replace one organization role permission bundle for an application. Contract: PUT /api/organizations/{orgId}/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "role": "example", "permissions": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permissions": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "included": { "type": "boolean" } }, "required": [ "orgId", "appId", "role", "permissions" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace organization role permissions.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_role_permissions.add Add one application permission to an organization role. Contract: POST /api/organizations/{orgId}/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add organization role permission.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_role_permissions.remove Remove one application permission from an organization role. Contract: DELETE /api/organizations/{orgId}/services/{appId}/role-permissions/{role}/{permission} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove organization role permission.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/services/{appId}/role-permissions/{role}/{permission}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo Brand source contract Human reference: https://docs.topolo.app/systems/topolo-brand Machine reference: https://docs.topolo.app/machine/systems/topolo-brand.json Source revisions: apps/TopoloBrand@05fc4a7e6712bb2cfabb4adee7fd95ba5935c992 Deploy targets: 2; implemented actions: 29; declared actions: 29; uncatalogued served routes: 1; mobile contracts: 0; route signals: 18. ### widget.get Get the TopoloOne widget summary. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.bootstrap Get the signed workspace bootstrap. Contract: GET /api/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/bootstrap without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.delete Delete an empty, non-default Brand workspace. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### privacy.export Export all Brand records and authenticated asset download paths owned by the selected workspace. Contract: GET /api/privacy/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/privacy/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.delete Erase all Brand records and asset bytes owned by the selected workspace. Contract: DELETE /api/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/privacy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### retention.run Pseudonymize expired actor identity and purge expired archived asset bytes. Contract: POST /api/privacy/retention Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/privacy/retention. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kits.list List canonical brand kits for the organization. Contract: GET /api/brand-kits Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-kits without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_kits.get Get one canonical brand kit. Contract: GET /api/brand-kits/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-kits/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_kits.create Create a canonical brand kit. Contract: POST /api/brand-kits Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "slug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "name", "slug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-kits. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kits.update Update brand kit metadata. Contract: PATCH /api/brand-kits/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/brand-kits/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kits.delete Permanently delete a Brand kit that was never published and has no connections, including its governed asset bytes. Refused with 409 otherwise — retire instead. Contract: DELETE /api/brand-kits/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/brand-kits/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kits.retire Retire a brand kit and stop new resolution. Contract: POST /api/brand-kits/{id}/retire Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-kits/{id}/retire. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kit_versions.list List immutable and draft versions for a brand kit. Contract: GET /api/brand-kits/{brandKitId}/versions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "brandKitId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-kits/{brandKitId}/versions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_kit_versions.get Get an exact brand kit version. Contract: GET /api/brand-kits/{brandKitId}/versions/{versionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "brandKitId": "example", "versionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-kits/{brandKitId}/versions/{versionId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_kit_versions.create Create a draft versioned brand snapshot. Contract: POST /api/brand-kits/{brandKitId}/versions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandKitId": "example", "snapshot": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "snapshot": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "changeNote": { "type": "string" } }, "required": [ "brandKitId", "snapshot" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-kits/{brandKitId}/versions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kit_versions.update Update a draft version before publishing. Contract: PATCH /api/brand-kits/{brandKitId}/versions/{versionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandKitId": "example", "versionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "snapshot": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "changeNote": { "type": "string" } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/brand-kits/{brandKitId}/versions/{versionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kit_versions.publish Publish an immutable brand snapshot for consumers. Refused with 422 and the failing issues when the snapshot breaks its own governance rules — an unresolved logo reference, or a palette below the brand’s declared minimum contrast. Contract: POST /api/brand-kits/{brandKitId}/versions/{versionId}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:publish Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandKitId": "example", "versionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-kits/{brandKitId}/versions/{versionId}/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kit_versions.discard Delete a working draft that was started and not wanted. Published and retired versions are immutable and cannot be discarded. Contract: DELETE /api/brand-kits/{brandKitId}/versions/{versionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "brandKitId": "example", "versionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/brand-kits/{brandKitId}/versions/{versionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kit_versions.restore Copy an earlier version’s snapshot into the working draft. The earlier version is never revived — published versions are immutable and consumers recorded their ids — so this produces an ordinary draft to review and publish. Contract: POST /api/brand-kits/{brandKitId}/versions/{versionId}/restore Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandKitId": "example", "versionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-kits/{brandKitId}/versions/{versionId}/restore. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kit_versions.request_review Assign a draft brand version to an organization member for review. Contract: POST /api/brand-kits/{brandKitId}/versions/{versionId}/review Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandKitId": "example", "versionId": "example", "reviewerUserId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "versionId": { "type": "string", "minLength": 1 }, "reviewerUserId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "versionId", "reviewerUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-kits/{brandKitId}/versions/{versionId}/review. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_bindings.list List consumer resources bound to brand kits. Contract: GET /api/brand-bindings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-bindings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_bindings.upsert Bind an app resource to a canonical brand kit. Contract: PUT /api/brand-bindings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "consumerAppId": "example", "externalResourceType": "example", "externalResourceId": "example", "brandKitId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "consumerAppId": { "type": "string", "minLength": 1 }, "externalResourceType": { "type": "string", "minLength": 1 }, "externalResourceId": { "type": "string", "minLength": 1 }, "brandKitId": { "type": "string", "minLength": 1 } }, "required": [ "consumerAppId", "externalResourceType", "externalResourceId", "brandKitId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/brand-bindings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_bindings.delete Remove a consumer resource brand binding. Contract: DELETE /api/brand-bindings/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/brand-bindings/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_kits.resolve Resolve the exact published brand version for a kit or consumer resource. Contract: POST /api/brand-kits:resolve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "brandKitId": "example", "consumerAppId": "example", "externalResourceType": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "consumerAppId": { "type": "string", "minLength": 1 }, "externalResourceType": { "type": "string", "minLength": 1 }, "externalResourceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through POST /api/brand-kits:resolve without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_kits.validate Check content, claims, CTAs, assets, and channel restrictions against a brand snapshot, plus the snapshot’s own logo references and palette contrast. Contract: POST /api/brand-kits:validate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "snapshot": {}, "text": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "snapshot": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "text": { "type": "string" }, "channel": { "type": "string", "minLength": 1 }, "ctaId": { "type": "string", "minLength": 1 }, "claimIds": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "assetIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "snapshot", "text" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through POST /api/brand-kits:validate without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_assets.list List registered logos, fonts, media, and templates for a kit. Contract: GET /api/brand-kits/{brandKitId}/assets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "brandKitId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/brand-kits/{brandKitId}/assets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### brand_assets.register Register an asset before uploading its content. Contract: POST /api/brand-assets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brandKitId": "example", "kind": "example", "name": "example", "mimeType": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brandKitId": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string", "minLength": 1 }, "license": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 } }, "required": [ "brandKitId", "kind", "name", "mimeType" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/brand-assets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_assets.upload Upload base64-encoded content into a registered Brand asset. Contract: PUT /api/brand-assets/{assetId}/content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "assetId": "example", "contentBase64": "/example", "contentType": "example", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 } }, "required": [ "assetId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/brand-assets/{assetId}/content. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### brand_assets.download Read authenticated Brand asset bytes for an allowed organization-bound consumer. Contract: GET /api/brand-assets/{assetId}/content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brand:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "assetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "assetId": { "type": "string", "minLength": 1 } }, "required": [ "assetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "properties": { "contentType": { "type": "string", "minLength": 1 }, "contentLength": { "type": "integer", "minimum": 0 }, "contentBase64": { "type": "string" } }, "required": [ "contentType", "contentLength", "contentBase64" ], "additionalProperties": false } ``` Effects: Reads state through GET /api/brand-assets/{assetId}/content without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## Topolo CLI source contract Human reference: https://docs.topolo.app/systems/topolo-cli Machine reference: https://docs.topolo.app/machine/systems/topolo-cli.json Source revisions: topolo-platform/packages/topolo-cli@515376de81efed9734741b2a1d691c8195243073 Deploy targets: 0; implemented actions: 0; declared actions: 0; uncatalogued served routes: 0; mobile contracts: 0; route signals: 0. ## Topolo Design source contract Human reference: https://docs.topolo.app/systems/topolo-design Machine reference: https://docs.topolo.app/machine/systems/topolo-design.json Source revisions: apps/TopoloDesign@b07fc4d973a6c3b8285bd2f506e830f88544e0b8 Deploy targets: 2; implemented actions: 36; declared actions: 38; uncatalogued served routes: 2; mobile contracts: 0; route signals: 18. ### widget.get Get the TopoloOne widget summary for Design. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean" }, "widgets": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": {} } } }, "required": [ "success", "widgets" ], "additionalProperties": {} } ``` Effects: Reads widget data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected widget context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### workspace.bootstrap Get the signed Design workspace bootstrap. Contract: GET /api/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "user": {}, "organization": {} }, "required": [ "user", "organization" ], "additionalProperties": false } ``` Effects: Reads the signed Design workspace bootstrap without changing workspace state. Verification: Use the returned workspace id only in the current credential context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### brands.list List accessible published Brand kits available for governed design creation. Contract: GET /api/brand-options Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: brands:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "available": { "type": "boolean" }, "brands": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "currentVersionId": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "currentVersionId" ], "additionalProperties": false } } }, "required": [ "available", "brands" ], "additionalProperties": false } ``` Effects: Reads brand data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected brand context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission brands:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### folders.list List workspace folders used to catalogue Design projects. Contract: GET /api/folders Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: folders:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } } }, "required": [ "folders" ], "additionalProperties": false } ``` Effects: Reads design_folder data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected design_folder context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission folders:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### folders.create Create a workspace folder for Design projects. Contract: POST /api/folders Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: folders:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "Launch campaign" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "folder" ], "additionalProperties": false } ``` Effects: Creates one workspace-scoped folder for cataloguing Design projects. Verification: Call app_topolo_design.folders.list and confirm the returned folder appears once. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission folders:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### folders.update Rename a workspace folder without changing its projects. Contract: PATCH /api/folders/{folderId} Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: folders:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "folderId": "design_folder_123", "name": "Product launch" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "folderId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "folder" ], "additionalProperties": false } ``` Effects: Rename a workspace folder without changing its projects. Verification: Validate the response against outputSchema and confirm it belongs to the selected design_folder context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission folders:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### folders.delete Delete a folder and move its projects to Unfiled. Contract: DELETE /api/folders/{folderId} Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: folders:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "folderId": "design_folder_123" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folderId": { "type": "string", "minLength": 1 } }, "required": [ "folderId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "folder": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "folder" ], "additionalProperties": false } ``` Effects: Deletes one folder and moves its projects to the unfiled collection without deleting projects. Verification: Call app_topolo_design.folders.list and confirm the folder is absent, then list projects and confirm their folderId is null. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission folders:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.list List active, archived, or all design projects in the selected workspace. Contract: GET /api/projects Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "scope": "active" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "default": "active", "type": "string", "enum": [ "active", "archived", "all" ] } }, "required": [ "scope" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 }, "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "pageCount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "createdAt", "updatedAt", "width", "height", "pageCount" ], "additionalProperties": false } } }, "required": [ "projects" ], "additionalProperties": false } ``` Effects: Reads design_project data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected design_project context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.get Get one editable, version-locked design project. Contract: GET /api/projects/{projectId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "projectId": "design_123" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } ``` Effects: Reads design_project data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected design_project context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.create Create an editable composition with an optional published Brand version. Contract: POST /api/projects Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "Launch banner", "width": 1080, "height": 1080, "starter": "blank" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandKitId": { "type": "string", "minLength": 1 }, "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "starter": { "default": "blank", "type": "string", "enum": [ "blank", "brand" ] } }, "required": [ "name", "starter" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } ``` Effects: Creates one editable design project, optionally pinned to an accessible published Brand version. Verification: Call app_topolo_design.projects.get with the returned project id and confirm its document and optional Brand provenance. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.copy Create an independent editable draft from an existing project while preserving its document and Brand provenance. Contract: POST /api/projects/{projectId}/copy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "projectId": "design_123", "name": "Launch banner variation" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } ``` Effects: Creates one independent draft project from the source document, preserving its pages, layout, assets, and published Brand provenance without copying exports. Verification: Call app_topolo_design.projects.get with the returned project id and confirm the document and Brand provenance match the source project. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.update Rename a project and/or replace its canvas document whole. Read the document with projects.get, modify it, and send the complete result back. Contract: PATCH /api/projects/{projectId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "projectId": "design_123", "name": "Updated launch banner", "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Page 1", "canvas": { "width": 1080, "height": 1080, "background": "#ffffff" }, "elements": [ { "id": "el_headline", "name": "Headline", "purpose": "headline", "type": "text", "frame": { "x": 80, "y": 120, "width": 920, "height": 200, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "Launch day", "style": { "fontFamily": "Inter", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 700, "lineHeight": 1.1, "letterSpacing": 0, "color": "#111111", "textAlign": "center", "verticalAlign": "middle" } }, { "id": "el_accent", "name": "Accent bar", "purpose": "decoration", "type": "shape", "kind": "rectangle", "frame": { "x": 80, "y": 360, "width": 920, "height": 12, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "style": { "fill": "#3355ff", "stroke": "#3355ff", "strokeWidth": 0, "cornerRadius": 6 } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [ { "elementId": "el_headline", "preset": "fade", "startMs": 0, "durationMs": 600, "easing": "ease-out" } ] } } ], "exportSettings": { "format": "png", "scale": 1, "quality": 0.92, "transparent": false } } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } ``` Effects: Renames, files, or stars one design project and/or replaces its entire canvas document with the provided one. Verification: Call app_topolo_design.projects.get and confirm the returned name, folder, star, and document match what was sent. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.archive Archive a design project without deleting its provenance or exports. Contract: DELETE /api/projects/{projectId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "projectId": "design_123" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } ``` Effects: Archives one design project so it no longer appears in the active project list. Verification: Call app_topolo_design.projects.get and confirm the returned project status is archived. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.delete Permanently remove one archived design project and every export taken from it. Refused unless the project is already archived. Contract: DELETE /api/projects/{projectId}/delete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "projectId": "design_launch" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "string" }, "exports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "deleted", "exports" ], "additionalProperties": false } ``` Effects: Permanently removes one archived design project and every export taken from it, including their stored objects. Refused with 409 unless the project is already archived. Verification: Call app_topolo_design.projects.list with scope archived and confirm the project id is absent. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### projects.restore Restore an archived design project to the editable draft list. Contract: POST /api/projects/{projectId}/restore Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "projectId": "design_123" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 } }, "required": [ "projectId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "project": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "project" ], "additionalProperties": false } ``` Effects: Restores one archived design project to draft status. Verification: Call app_topolo_design.projects.get and confirm the returned project status is draft. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission projects:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### exports.list List ready, pending, or all generated Design exports stored for the selected workspace. Contract: GET /api/exports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "status": "ready" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "default": "ready", "type": "string", "enum": [ "ready", "pending", "all" ] } }, "required": [ "status" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } } }, "required": [ "exports" ], "additionalProperties": false } ``` Effects: Lists immutable Design media records stored for the selected workspace without downloading their content. Verification: Confirm every returned export belongs to the selected workspace and use exports.get before downloading content. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission exports:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### exports.estimate Estimate the output size for a static or animated Design export without creating it. Contract: POST /api/projects/{projectId}/exports/estimate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "default": 0.92, "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "pages": { "default": "first", "description": "MP4 only. \"all\" exports the whole document as one video, laying every page end to end with each page’s declared transition between them; its length comes from the document, not from durationMs.", "type": "string", "enum": [ "first", "all" ] } }, "required": [ "projectId", "format", "width", "height", "quality", "pages" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "estimate": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "quality": { "type": "number" }, "durationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "fps": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "format", "width", "height", "quality", "estimatedByteSize" ], "additionalProperties": false } }, "required": [ "estimate" ], "additionalProperties": false } ``` Effects: Calculates a deterministic export-size estimate without creating an export or rendering content. Verification: Confirm the returned format, dimensions, duration, frame rate, and estimatedByteSize match the requested settings. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission exports:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### exports.create Create a design export. SVG, PNG, and JPEG return ready. Short MP4 clips return ready too; longer clips return pending while the service encodes in the background — poll exports.get or await the export-ready notification. Contract: POST /api/projects/{projectId}/exports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "projectId": "design_123", "format": "png", "width": 1080, "height": 1080, "quality": 0.92, "pages": "first", "altText": "Launch announcement" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "default": 0.92, "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "pages": { "default": "first", "description": "MP4 only. \"all\" exports the whole document as one video, laying every page end to end with each page’s declared transition between them; its length comes from the document, not from durationMs.", "type": "string", "enum": [ "first", "all" ] }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "projectId", "format", "width", "height", "quality", "pages", "altText" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "export": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "export" ], "additionalProperties": false } ``` Effects: Creates an immutable export record. Stills and short clips come back ready; a longer MP4 comes back pending and the service encodes it in the background until exports.get reports ready. Verification: Call app_topolo_design.exports.get with the returned export id and confirm its status and dimensions. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission exports:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### exports.upload Upload rendered PNG, JPEG, or short MP4 bytes for an export still pending. The service renders these formats itself, so this is a fallback for content it could not produce. Contract: PUT /api/exports/{exportId}/content Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "exportId": "export_123", "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 34952536, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "video/mp4" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "exportId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "export": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } }, "required": [ "export" ], "additionalProperties": false } ``` Effects: Stores raster or MP4 bytes for one pending export and marks the export ready. Verification: Call app_topolo_design.exports.get and confirm the export status is ready and byteSize matches the uploaded content. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission exports:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### exports.get Get export metadata and the authenticated content URL for a Design export. Contract: GET /api/exports/{exportId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "exportId": "export_123" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string", "minLength": 1 } }, "required": [ "exportId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "export": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "export", "contentUrl" ], "additionalProperties": false } ``` Effects: Reads design_export data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected design_export context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission exports:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### exports.handoff Create a media descriptor for Social Studio or Socialize from a ready export. Contract: POST /api/exports/{exportId}/handoffs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: exports:handoff Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "exportId": "export_123", "target": "socialize" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "exportId": { "type": "string", "minLength": 1 }, "target": { "type": "string", "enum": [ "social_studio", "socialize" ] }, "externalResourceId": { "type": "string", "minLength": 1 } }, "required": [ "exportId", "target" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "handoff": { "type": "object", "properties": { "target": { "type": "string", "enum": [ "social_studio", "socialize" ] }, "externalResourceId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "projectId": { "type": "string", "minLength": 1 }, "exportId": { "type": "string", "minLength": 1 }, "mediaUrl": { "type": "string", "minLength": 1 }, "requiresCredential": { "type": "boolean" }, "filename": { "type": "string", "minLength": 1 }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "altText": { "type": "string", "minLength": 1 } }, "required": [ "target", "externalResourceId", "projectId", "exportId", "mediaUrl", "requiresCredential", "filename", "mediaType", "mimeType", "width", "height", "durationMs", "fps", "byteSize", "altText" ], "additionalProperties": false } }, "required": [ "handoff" ], "additionalProperties": false } ``` Effects: Returns a provenance-preserving media descriptor for a ready export without mutating the target application. Verification: Confirm the descriptor exportId, projectId, MIME type, dimensions, and authenticated content URL match app_topolo_design.exports.get. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission exports:handoff and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### media.list List reusable source images and videos uploaded to the selected Design workspace. Contract: GET /api/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: media:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 48 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "minLength": 1 }, "limit": { "default": 48, "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "limit" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "upload" }, "name": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "projectId": { "type": "null" }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "webp", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "width": { "type": "null" }, "height": { "type": "null" }, "durationMs": { "type": "null" }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "ready" }, "createdAt": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "id", "source", "name", "fileName", "projectId", "format", "mimeType", "mediaType", "width", "height", "durationMs", "altText", "byteSize", "status", "createdAt", "contentUrl" ], "additionalProperties": false } }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "media", "nextCursor" ], "additionalProperties": false } ``` Effects: Lists reusable source media uploaded to the selected Design workspace. Generated exports are intentionally excluded. Verification: Confirm each returned item is an uploaded source asset in the selected workspace. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission media:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### media.upload Upload a reusable source image or video to the selected Design workspace Media library. Contract: POST /api/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: media:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "launch.png", "altText": "Launch artwork" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1, "maxLength": 34952536, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "altText": { "type": "string", "maxLength": 500 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "upload" }, "name": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "projectId": { "type": "null" }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "webp", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "width": { "type": "null" }, "height": { "type": "null" }, "durationMs": { "type": "null" }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "ready" }, "createdAt": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "id", "source", "name", "fileName", "projectId", "format", "mimeType", "mediaType", "width", "height", "durationMs", "altText", "byteSize", "status", "createdAt", "contentUrl" ], "additionalProperties": false } }, "required": [ "media" ], "additionalProperties": false } ``` Effects: Stores one reusable source asset in the selected workspace media library. Verification: Call app_topolo_design.media.list and confirm the returned id, filename, MIME type, and byte size. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission media:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### media.generate Generate an image through the governed provider gateway and store it in the selected Design workspace. Contract: POST /api/media/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: media:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "prompt": "A bold editorial illustration of software removing repetitive work", "aspectRatio": "4:3" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "prompt": { "type": "string", "minLength": 10, "maxLength": 1000 }, "aspectRatio": { "type": "string", "enum": [ "1:1", "16:9", "9:16", "4:3", "3:4" ] }, "provider": { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, "model": { "type": "string", "minLength": 1, "maxLength": 200 }, "sourceAsset": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "mimeType": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "url" ], "additionalProperties": false }, "fileName": { "type": "string", "minLength": 1, "maxLength": 120 }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "prompt" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "upload" }, "name": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "projectId": { "type": "null" }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "webp", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "width": { "type": "null" }, "height": { "type": "null" }, "durationMs": { "type": "null" }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "ready" }, "createdAt": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "id", "source", "name", "fileName", "projectId", "format", "mimeType", "mediaType", "width", "height", "durationMs", "altText", "byteSize", "status", "createdAt", "contentUrl" ], "additionalProperties": false }, "generation": { "type": "object", "properties": { "provider": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "model": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "provider", "model" ], "additionalProperties": false } }, "required": [ "media", "generation" ], "additionalProperties": false } ``` Effects: Generates one image through the governed provider gateway and stores it as reusable workspace media. Verification: Call app_topolo_design.media.list and confirm the generated media id, MIME type, and content URL. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission media:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### media.delete_availability Check whether a source asset is unreferenced and safe to delete. Contract: GET /api/media/{mediaId}/deletion Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: media:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "mediaId": "design_media_123" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "mediaId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "allowed": { "type": "boolean" }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "allowed" ], "additionalProperties": false } ``` Effects: Checks whether workspace media is unreferenced and therefore safe to delete without changing it. Verification: Treat allowed false and its reason as authoritative; do not call media.delete until allowed is true. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission media:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### media.delete Permanently delete an unreferenced source asset from the selected Design workspace Media library. Contract: DELETE /api/media/{mediaId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: media:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "mediaId": "design_media_123" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "mediaId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deleted": { "type": "boolean", "const": true }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "deleted", "mediaId" ], "additionalProperties": false } ``` Effects: Permanently removes one unreferenced source asset from the selected workspace media library. Verification: Call app_topolo_design.media.list and confirm the deleted media id is absent. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission media:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### fonts.list List uploaded workspace fonts and their authenticated content URLs. Contract: GET /api/fonts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: fonts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fonts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "workspace" }, "contentType": { "type": "string", "enum": [ "font/woff2", "font/woff", "application/font-woff", "font/ttf", "application/x-font-ttf", "font/otf", "application/x-font-opentype" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] }, "contentUrl": { "type": "string", "minLength": 1 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" } }, "required": [ "id", "family", "source", "contentType", "format", "contentUrl" ], "additionalProperties": false } } }, "required": [ "fonts" ], "additionalProperties": false } ``` Effects: Lists workspace font assets with authenticated content URLs for use in Design documents. Verification: Confirm each font belongs to the selected workspace and has a supported content type and format. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission fonts:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### fonts.upload Upload one licensed font file for use in Design documents. Contract: POST /api/fonts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: fonts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "family": "Acme Sans", "fileName": "acme.woff2", "contentType": "font/woff2", "contentBase64": "Zm9udA==", "license": "Company licence" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 120 }, "fileName": { "type": "string", "minLength": 1, "maxLength": 240 }, "contentType": { "type": "string", "enum": [ "font/woff2", "font/woff", "application/font-woff", "font/ttf", "application/x-font-ttf", "font/otf", "application/x-font-opentype" ] }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 2796204, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "license": { "type": "string", "minLength": 1, "maxLength": 240 } }, "required": [ "family", "fileName", "contentType", "contentBase64", "license" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "font": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "const": "workspace" }, "contentType": { "type": "string", "enum": [ "font/woff2", "font/woff", "application/font-woff", "font/ttf", "application/x-font-ttf", "font/otf", "application/x-font-opentype" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] }, "contentUrl": { "type": "string", "minLength": 1 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" } }, "required": [ "id", "family", "source", "contentType", "format", "sourceUrl" ], "additionalProperties": false } }, "required": [ "font" ], "additionalProperties": false } ``` Effects: Stores one licensed font file in the selected Design workspace and returns a document-ready embedded source URL. Verification: Call app_topolo_design.fonts.list and confirm the returned font id, family, content type, and format. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission fonts:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### stock.list List the shared searchable Design stock image collection. Contract: GET /api/stock Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "stock": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "orientation": { "type": "string", "enum": [ "portrait", "landscape", "square" ] }, "altText": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "name", "title", "tags", "orientation", "altText", "contentUrl" ], "additionalProperties": false } } }, "required": [ "stock" ], "additionalProperties": false } ``` Effects: Lists the shared Design stock collection with searchable metadata and public immutable content paths. Verification: Confirm each returned stock name is a safe collection entry before using /api/stock/{name}. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission workspace:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### stock.upload Add an approved image to the immutable stock collection shared by every Design workspace. Contract: POST /api/stock Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: library:publish Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contentBase64": "aGVsbG8=", "contentType": "image/png", "fileName": "shared-table.png", "altText": "A shared table of dishes." } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contentBase64": { "type": "string", "minLength": 1, "maxLength": 13981016, "pattern": "^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$" }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 240 }, "altText": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "stock": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "orientation": { "type": "string", "enum": [ "portrait", "landscape", "square" ] }, "altText": { "type": "string", "minLength": 1 }, "contentUrl": { "type": "string", "minLength": 1 } }, "required": [ "name", "title", "tags", "orientation", "altText", "contentUrl" ], "additionalProperties": false }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "stock", "byteSize" ], "additionalProperties": false } ``` Effects: Adds one content-addressed image to the immutable stock collection shared by every Design workspace. Verification: Call app_topolo_design.stock.list and confirm the returned content-addressed stock name and metadata are present. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission library:publish and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### settings.get Get workspace canvas, Brand, export, and motion defaults for Design. Contract: GET /api/settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultCanvasHeight": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "defaultExportScale": { "type": "number" }, "defaultExportQuality": { "type": "number" }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "required": [ "defaultBrandKitId", "defaultCanvasWidth", "defaultCanvasHeight", "defaultExportFormat", "defaultExportScale", "defaultExportQuality", "defaultExportTransparent", "defaultAnimationDurationMs", "defaultAnimationFps" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } ``` Effects: Reads workspace data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected workspace context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission settings:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### settings.update Update workspace canvas, Brand, export, or motion defaults for Design. Contract: PATCH /api/settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "defaultBrandKitId": "brand_123", "defaultCanvasWidth": 1080, "defaultCanvasHeight": 1350, "defaultExportFormat": "png" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": 64, "maximum": 8192 }, "defaultCanvasHeight": { "type": "integer", "minimum": 64, "maximum": 8192 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "defaultExportScale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "defaultExportQuality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": 1500, "maximum": 30000 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "settings": { "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultCanvasHeight": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "defaultExportScale": { "type": "number" }, "defaultExportQuality": { "type": "number" }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "required": [ "defaultBrandKitId", "defaultCanvasWidth", "defaultCanvasHeight", "defaultExportFormat", "defaultExportScale", "defaultExportQuality", "defaultExportTransparent", "defaultAnimationDurationMs", "defaultAnimationFps" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } ``` Effects: Updates workspace defaults used when new Design projects are created. Verification: Call app_topolo_design.settings.get and confirm the persisted defaults match the request. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission settings:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### privacy.export Export Design projects, uploaded media metadata, generated export metadata, and settings for the selected workspace. Contract: GET /api/privacy/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "draft", "ready", "archived" ] }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "starred": { "type": "boolean" }, "brandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "brandVersionId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." }, "createdAt": { "type": "string", "minLength": 1 }, "updatedAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "status", "folderId", "starred", "brandKitId", "brandVersionId", "document", "createdAt", "updatedAt" ], "additionalProperties": false } }, "exports": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "video/mp4" ] }, "width": { "type": "integer", "minimum": 320, "maximum": 4096 }, "height": { "type": "integer", "minimum": 320, "maximum": 4096 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "durationMs": { "anyOf": [ { "type": "integer", "minimum": 500, "maximum": 30000 }, { "type": "null" } ] }, "fps": { "anyOf": [ { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, { "type": "null" } ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "estimatedByteSize": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "byteSize": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "pending", "ready" ] }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "projectId", "format", "mimeType", "width", "height", "quality", "durationMs", "fps", "storageKey", "altText", "estimatedByteSize", "byteSize", "status", "createdAt" ], "additionalProperties": false } }, "media": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "mimeType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp", "video/mp4" ] }, "mediaType": { "type": "string", "enum": [ "image", "video" ] }, "storageKey": { "type": "string", "minLength": 1 }, "altText": { "type": "string", "minLength": 1 }, "byteSize": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "createdAt": { "type": "string", "minLength": 1 } }, "required": [ "id", "fileName", "mimeType", "mediaType", "storageKey", "altText", "byteSize", "createdAt" ], "additionalProperties": false } }, "settings": { "type": "object", "properties": { "defaultBrandKitId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultCanvasWidth": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultCanvasHeight": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultExportFormat": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4" ] }, "defaultExportScale": { "type": "number" }, "defaultExportQuality": { "type": "number" }, "defaultExportTransparent": { "type": "boolean" }, "defaultAnimationDurationMs": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "defaultAnimationFps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] } }, "required": [ "defaultBrandKitId", "defaultCanvasWidth", "defaultCanvasHeight", "defaultExportFormat", "defaultExportScale", "defaultExportQuality", "defaultExportTransparent", "defaultAnimationDurationMs", "defaultAnimationFps" ], "additionalProperties": false } }, "required": [ "projects", "exports", "media", "settings" ], "additionalProperties": false } ``` Effects: Reads workspace data without changing service state. Verification: Validate the response against outputSchema and confirm it belongs to the selected workspace context. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission privacy:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### library.list List one page of the starter templates published to every workspace. Returns card metadata without documents; needs no workspace of its own. Contract: GET /api/templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: library:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 12, "category": "Social" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "integer", "minimum": 1, "maximum": 60 }, "category": { "type": "string", "enum": [ "Social", "Presentations", "Documents", "Marketing", "Print" ] }, "style": { "type": "string", "enum": [ "Bold", "Minimal", "Editorial", "Playful", "Professional" ] }, "q": { "type": "string", "minLength": 1, "maxLength": 120 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "style": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updatedAt": { "type": "string" } }, "required": [ "id", "name", "description", "category", "style", "width", "height", "pageCount", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "nextCursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "templates", "total", "nextCursor" ], "additionalProperties": false } ``` Effects: Reads one page of the starter library, which is shared by every workspace and needs none. Returns card metadata without documents; pass the returned nextCursor to read the following page. Verification: Confirm the returned page count matches the requested limit and that nextCursor is null on the last page. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission library:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### library.get Read one starter-library template including its full design document. Needs no workspace of its own. Contract: GET /api/templates/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: library:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "after-hours-launch" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "style": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updatedAt": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "id", "name", "description", "category", "style", "width", "height", "pageCount", "updatedAt", "document" ], "additionalProperties": false } }, "required": [ "template" ], "additionalProperties": false } ``` Effects: Reads one starter-library template including its full design document. Verification: Confirm the returned document carries at least one page and the id matches the request. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission library:read and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### library.publish Publish a design into the starter library shared by every workspace, or replace the one already published under this id. Only the organization that owns Design may call this. Contract: POST /api/templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: library:publish Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "starter-launch-post", "name": "Launch post", "summary": "A single-card launch announcement.", "category": "Social", "style": "Bold", "rank": 0, "document": { "schemaVersion": 5, "brand": null, "fontSources": [], "pages": [ { "id": "page_1", "name": "Cover", "canvas": { "width": 1080, "height": 1350, "background": "#0A2440" }, "elements": [ { "id": "title", "name": "Display title", "purpose": "Headline", "type": "text", "frame": { "x": 92, "y": 400, "width": 896, "height": 240, "rotation": 0 }, "opacity": 1, "hidden": false, "locked": false, "text": "A starter design", "style": { "fontFamily": "Helvetica Neue, Helvetica, Arial, sans-serif", "fontSize": 96, "minFontSize": 48, "maxFontSize": 96, "autoFit": true, "fontWeight": 800, "lineHeight": 1.05, "letterSpacing": -2, "color": "#FFFFFF", "textAlign": "left", "verticalAlign": "middle" } } ], "animation": { "durationMs": 3000, "fps": 24, "motions": [] } } ], "exportSettings": { "format": "png", "scale": 2, "quality": 0.92, "transparent": false } } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "summary": { "default": "", "type": "string", "maxLength": 280 }, "category": { "default": "Documents", "type": "string", "enum": [ "Social", "Presentations", "Documents", "Marketing", "Print" ] }, "style": { "default": "Minimal", "type": "string", "enum": [ "Bold", "Minimal", "Editorial", "Playful", "Professional" ] }, "rank": { "default": 0, "type": "integer", "minimum": 0, "maximum": 9999 }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "id", "name", "summary", "category", "style", "rank", "document" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "template": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "style": { "type": "string" }, "width": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "height": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pageCount": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "updatedAt": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 5 }, "brand": { "anyOf": [ { "type": "object", "properties": { "kitId": { "type": "string", "minLength": 1, "maxLength": 280 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 280 }, "name": { "type": "string", "minLength": 1, "maxLength": 280 }, "primary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "secondary": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "accent": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "foreground": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "headingFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "bodyFont": { "type": "string", "minLength": 1, "maxLength": 280 }, "logoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedLogoUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "markUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "reversedMarkUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] }, "lockupUrl": { "anyOf": [ { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, { "type": "null" } ] } }, "required": [ "kitId", "versionId", "name", "primary", "secondary", "accent", "background", "foreground", "headingFont", "bodyFont", "logoUrl", "reversedLogoUrl", "markUrl", "reversedMarkUrl", "lockupUrl" ], "additionalProperties": false }, { "type": "null" } ] }, "fontSources": { "maxItems": 4, "type": "array", "items": { "type": "object", "properties": { "family": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "type": "string", "pattern": "^data:[^;,]+;base64,[A-Za-z0-9+/]+={0,2}$" }, "weight": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 900 }, { "type": "string", "pattern": "^\\d{3} \\d{3}$" } ] }, "style": { "type": "string", "enum": [ "normal", "italic" ] }, "format": { "type": "string", "enum": [ "woff2", "woff", "truetype", "opentype" ] } }, "required": [ "family", "sourceUrl", "weight" ], "additionalProperties": false } }, "pages": { "minItems": 1, "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "transition": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-left", "slide-right", "slide-up", "slide-down" ] }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 5000 } }, "required": [ "preset", "durationMs" ], "additionalProperties": false, "description": "How this page arrives from the one before it when the document is exported as one video. The first page has nothing to arrive from, so it cannot carry one; a page without a transition cuts straight in." }, "canvas": { "type": "object", "properties": { "width": { "type": "integer", "minimum": 64, "maximum": 8192 }, "height": { "type": "integer", "minimum": 64, "maximum": 8192 }, "background": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "backgroundImage": { "type": "object", "properties": { "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "sourceUrl", "altText", "fit" ], "additionalProperties": false } }, "required": [ "width", "height", "background" ], "additionalProperties": false }, "elements": { "maxItems": 500, "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "text": { "type": "string", "maxLength": 10000 }, "style": { "type": "object", "properties": { "fontFamily": { "type": "string", "minLength": 1, "maxLength": 160 }, "fontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "minFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "maxFontSize": { "type": "number", "exclusiveMinimum": 0, "maximum": 1024 }, "autoFit": { "type": "boolean" }, "fontWeight": { "type": "integer", "minimum": 100, "maximum": 900 }, "lineHeight": { "type": "number", "minimum": 0.5, "maximum": 4 }, "letterSpacing": { "type": "number", "minimum": -100, "maximum": 500 }, "color": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] } }, "required": [ "fontFamily", "fontSize", "minFontSize", "maxFontSize", "autoFit", "fontWeight", "lineHeight", "letterSpacing", "color", "textAlign", "verticalAlign" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "text", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "kind": { "default": "rectangle", "type": "string", "enum": [ "rectangle", "circle", "ellipse", "triangle", "line" ] }, "style": { "type": "object", "properties": { "fill": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "stroke": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "strokeWidth": { "type": "number", "minimum": 0, "maximum": 512 }, "cornerRadius": { "type": "number", "minimum": 0, "maximum": 4096 } }, "required": [ "fill", "stroke", "strokeWidth", "cornerRadius" ], "additionalProperties": false } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "kind", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 }, "groupId": { "type": "string", "minLength": 1, "maxLength": 160 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "purpose": { "type": "string", "maxLength": 120 }, "frame": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "height": { "type": "number", "exclusiveMinimum": 0, "maximum": 8192 }, "rotation": { "type": "number", "minimum": -360, "maximum": 360 } }, "required": [ "x", "y", "width", "height", "rotation" ], "additionalProperties": false, "description": "Element placement in canvas pixels. x/y is the top-left corner relative to the canvas origin (top-left); rotation is degrees clockwise." }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "hidden": { "type": "boolean" }, "locked": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "mediaAssetId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sourceUrl": { "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "format": "uri" } ] }, "altText": { "type": "string", "maxLength": 500 }, "fit": { "type": "string", "enum": [ "cover", "contain", "fill" ] } }, "required": [ "id", "name", "purpose", "frame", "opacity", "hidden", "locked", "type", "sourceUrl", "altText", "fit" ], "additionalProperties": false } ] }, "description": "Layered page content painted in array order (later elements render on top)." }, "animation": { "type": "object", "properties": { "durationMs": { "type": "integer", "minimum": 500, "maximum": 30000 }, "fps": { "anyOf": [ { "type": "number", "const": 12 }, { "type": "number", "const": 24 }, { "type": "number", "const": 30 } ] }, "motions": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "elementId": { "type": "string", "minLength": 1, "maxLength": 160 }, "preset": { "type": "string", "enum": [ "none", "fade", "slide-up", "slide-left", "zoom-in", "pulse" ], "description": "How the layer enters. Use \"none\" to hold the layer from the first frame and give it an exit only." }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] }, "exit": { "type": "object", "properties": { "preset": { "type": "string", "enum": [ "fade", "slide-up", "slide-down", "slide-left", "slide-right", "zoom-out" ] }, "startMs": { "type": "integer", "minimum": 0, "maximum": 30000 }, "durationMs": { "type": "integer", "minimum": 100, "maximum": 30000 }, "easing": { "type": "string", "enum": [ "linear", "ease", "ease-in", "ease-out", "ease-in-out" ] } }, "required": [ "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false, "description": "How the layer leaves the clip after its entrance has finished." } }, "required": [ "elementId", "preset", "startMs", "durationMs", "easing" ], "additionalProperties": false } } }, "required": [ "durationMs", "fps", "motions" ], "additionalProperties": false } }, "required": [ "id", "name", "canvas", "elements", "animation" ], "additionalProperties": false } }, "exportSettings": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "svg", "png", "jpeg", "mp4", "pdf", "pptx" ] }, "scale": { "type": "number", "minimum": 0.25, "maximum": 4 }, "quality": { "type": "number", "minimum": 0.1, "maximum": 1 }, "transparent": { "type": "boolean" } }, "required": [ "format", "scale", "quality", "transparent" ], "additionalProperties": false } }, "required": [ "schemaVersion", "brand", "fontSources", "pages", "exportSettings" ], "additionalProperties": false, "description": "The complete paged design document. All sections are required; schemaVersion is the literal 5. Sending a document replaces the stored document whole." } }, "required": [ "id", "name", "description", "category", "style", "width", "height", "pageCount", "updatedAt", "document" ], "additionalProperties": false } }, "required": [ "template" ], "additionalProperties": false } ``` Effects: Publishes one design into the starter library shared by every workspace, or replaces the one already published under this id. Refused unless the calling organization owns the Design application. Verification: Call app_topolo_design.library.list and confirm the template appears with the expected name and page count. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission library:publish and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### library.retire Remove a template from the starter library without deleting the project behind it. Only the organization that owns Design may call this. Contract: DELETE /api/templates/:id Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: library:publish Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "starter-launch-post" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "retired": { "type": "string" } }, "required": [ "retired" ], "additionalProperties": false } ``` Effects: Removes one template from the starter library without deleting the project behind it. Refused unless the calling organization owns the Design application. Verification: Call app_topolo_design.library.list and confirm the template is no longer listed. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission library:publish and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ### privacy.erase Permanently erase Design projects, uploaded media, generated exports, and settings for the selected workspace. Contract: DELETE /api/privacy/erase Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "erased": { "type": "boolean", "const": true }, "projects": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "exports": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "media": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "erased", "projects", "exports", "media" ], "additionalProperties": false } ``` Effects: Permanently erases Design projects, export records, and generated R2 objects for the selected workspace. Verification: Call app_topolo_design.privacy.export and confirm both projects and exports are empty. Recovery: [object Object] 401 authentication_required: Authenticate again or provide a valid Topolo API key. 403 permission_denied: Grant the credential permission privacy:write and the required workspace binding. 422 invalid_input: Correct the payload using inputSchema, then validate before retrying. 429 rate_limited: Wait for Retry-After when present, then retry without parallel duplicate calls. 503 dependency_unavailable: Retry the action. If it continues, inspect the structured error details using the request ID. ## Topolo Developers source contract Human reference: https://docs.topolo.app/systems/topolo-developers Machine reference: https://docs.topolo.app/machine/systems/topolo-developers.json Source revisions: apps/TopoloDevelopers@690f230abf462c7a526b16186b94b7fc05e210dd Deploy targets: 3; implemented actions: 59; declared actions: 59; uncatalogued served routes: 0; mobile contracts: 1; route signals: 31. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.list List apps owned by the developer workspace. Contract: GET /api/developer-console/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List developer apps.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/apps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.create Create a developer app registration. Contract: POST /api/developer-console/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 100 }, "description": { "type": "string", "maxLength": 2000 }, "category": { "type": "string", "maxLength": 80 }, "distributionModel": { "type": "string", "enum": [ "marketplace", "organization_internal" ] }, "pricingType": { "type": "string", "enum": [ "free", "paid" ] }, "version": { "type": "string" }, "supportEmail": { "type": "string" }, "websiteUrl": { "type": "string" }, "demoUrl": { "type": "string" }, "repoUrl": { "type": "string" }, "notes": { "type": "string" }, "monthlyPrice": { "anyOf": [ { "type": "number" }, { "type": "string", "const": "" }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "screenshots": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "members": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "addedAt": { "type": "string" } }, "required": [ "email", "role" ], "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create developer app.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.get Get one developer app registration. Contract: GET /api/developer-console/apps/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get developer app.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/apps/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.update Update one developer app registration. Contract: PATCH /api/developer-console/apps/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" }, "distributionModel": { "type": "string", "enum": [ "marketplace", "organization_internal" ] }, "pricingType": { "type": "string", "enum": [ "free", "paid" ] }, "version": { "type": "string" }, "supportEmail": { "type": "string" }, "websiteUrl": { "type": "string" }, "demoUrl": { "type": "string" }, "repoUrl": { "type": "string" }, "notes": { "type": "string" }, "monthlyPrice": { "anyOf": [ { "type": "number" }, { "type": "string", "const": "" }, { "type": "null" } ] }, "tags": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "screenshots": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "string" } ] }, "members": { "minItems": 1, "maxItems": 12, "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "enum": [ "owner", "admin", "developer", "viewer" ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "addedAt": { "type": "string" } }, "required": [ "email", "role" ], "additionalProperties": false } }, "appStatus": { "type": "string", "enum": [ "draft", "configured", "archived" ] } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update developer app.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/developer-console/apps/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.submit Submit an app for review. Contract: POST /api/developer-console/apps/{appId}/submit Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: submissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Submit developer app.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/submit. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### build_requests.list List developer build requests. Contract: GET /api/developer-console/build-requests Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: requests:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List build requests.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/build-requests without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### build_requests.create Submit a developer build request for a community or company application. Contract: POST /api/developer-console/build-requests Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: requests:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "summary": "examplexxxxxxxxxxxxx" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestType": { "type": "string", "enum": [ "community", "company" ] }, "title": { "type": "string", "minLength": 4, "maxLength": 140 }, "summary": { "type": "string", "minLength": 20, "maxLength": 2000 }, "impact": { "type": "string", "maxLength": 1000 }, "budgetContext": { "type": "string", "maxLength": 500 } }, "required": [ "title", "summary" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create build request.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/build-requests. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### review.submissions.list List app submissions awaiting review. Contract: GET /api/developer-console/review/app-submissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: review:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List app submissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/review/app-submissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### review.submissions.review Review an app submission. Contract: POST /api/developer-console/review/app-submissions/{submissionId}/review Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: review:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "submissionId": "example", "status": "pending" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "submissionId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "in_review", "approved", "rejected", "requires_changes" ] }, "rejectionReason": { "type": "string", "maxLength": 1000 } }, "required": [ "submissionId", "status" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Review app submission.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/review/app-submissions/{submissionId}/review. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### catalog.embeddings.sync Process one bounded page of stale, selected, or all catalog application embeddings. Contract: POST /api/catalog/embeddings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "cursor": "2026-01-01", "limit": 1, "all": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,256}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "all": { "type": "boolean" }, "appId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "properties": { "ok": { "type": "boolean" }, "embedded": { "type": "integer" }, "failed": { "type": "integer" }, "scanned": { "type": "integer" }, "page": { "type": "object", "additionalProperties": true } }, "required": [ "ok", "embedded", "failed", "scanned", "page" ], "additionalProperties": true } ``` Effects: May change state through POST /api/catalog/embeddings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### catalog.registry.reconcile Republish one developer application into the public catalog projection. Contract: POST /api/internal/registry-reconcile Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "properties": { "source": { "type": "string", "const": "developer-apps" }, "operation": { "type": "string", "const": "registry-reconcile" }, "appId": { "type": "string", "minLength": 1 }, "total": { "type": "integer", "minimum": 0, "maximum": 1 }, "published": { "type": "integer", "minimum": 0, "maximum": 1 }, "skipped": { "type": "integer", "minimum": 0, "maximum": 1 }, "skippedAppIds": { "type": "array", "items": { "type": "string" }, "maxItems": 1 }, "failed": { "type": "integer", "minimum": 0, "maximum": 1 }, "failures": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string" }, "error": { "type": "string" } }, "required": [ "appId", "error" ], "additionalProperties": false }, "maxItems": 1 }, "page": { "type": "object", "properties": { "nextCursor": { "type": "null" }, "hasMore": { "type": "boolean", "const": false } }, "required": [ "nextCursor", "hasMore" ], "additionalProperties": false } }, "required": [ "source", "operation", "appId", "total", "published", "skipped", "skippedAppIds", "failed", "failures", "page" ], "additionalProperties": false } ``` Effects: Republishes the current developer application metadata into the public catalog projection for exactly one app. Verification: Call app_topolo_developers.catalog.search with q equal to the appId and confirm the returned catalog entry matches the current developer application metadata. Recovery: 401 authentication_required: Authenticate again with the intended Topolo environment. 403 permission_denied: Use a credential with marketplace:write permission for Topolo Developers. 422 invalid_input: Provide exactly one non-empty appId and validate the action before retrying. 502 registry_reconcile_failed: Inspect the returned failure for the selected app, correct its source metadata, and retry the unchanged appId. ### notifications.catalog.list Search the app-owned notification event and projection catalog. Contract: GET /api/catalog/notifications Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example", "app": "example", "status": "draft" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "app": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "deprecated" ] }, "deliveryClass": { "type": "string", "enum": [ "automation", "notification", "action", "transactional" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "cursor": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "required": [ "notifications", "count", "page" ], "properties": { "notifications": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "count": { "type": "integer" }, "page": { "type": "object", "additionalProperties": true } }, "additionalProperties": false } ``` Effects: Reads state through GET /api/catalog/notifications without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### catalog.search Search the live app catalog. Contract: GET /api/catalog/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 40 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Search app catalog.", "additionalProperties": true } ``` Effects: Reads state through GET /api/catalog/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.summary.get Execute workspace.summary.get in Topolo Developers. Contract: GET /api/developer-console/summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.onboarding.get Execute workspace.onboarding.get in Topolo Developers. Contract: GET /api/developer-console/onboarding Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/onboarding without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.onboarding.update Execute workspace.onboarding.update in Topolo Developers. Contract: PUT /api/developer-console/onboarding Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/onboarding. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.scaffold Execute apps.scaffold in Topolo Developers. Contract: POST /api/developer-console/apps/scaffold Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/scaffold. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.reconcile Check or apply a declarative third-party application registration for the authenticated developer organization. Contract: POST /api/developer-console/apps/reconcile Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "mode": { "type": "string", "enum": [ "check", "apply" ] }, "healthcheckPath": {}, "callbackUrls": { "type": "array", "items": { "type": "string" } }, "requestedScopes": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "marketplace": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "notifications": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "actions": { "type": "array", "maxItems": 250, "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/reconcile. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.claim_transfer Execute apps.claim_transfer in Topolo Developers. Contract: POST /api/developer-console/apps/claim-transfer Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/claim-transfer. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.transfer Execute apps.transfer in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/transfer Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/transfer. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.icon.upload Execute apps.icon.upload in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/icon Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "contentBase64": "example", "contentType": "image/svg+xml", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 350000 }, "contentType": { "type": "string", "enum": [ "image/svg+xml", "image/png", "image/jpeg", "image/webp" ] }, "fileName": { "type": "string", "minLength": 1 } }, "required": [ "appId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/icon. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.marketing.get Execute apps.marketing.get in Topolo Developers. Contract: GET /api/developer-console/apps/{appId}/marketing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/apps/{appId}/marketing without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.marketing.update Execute apps.marketing.update in Topolo Developers. Contract: PUT /api/developer-console/apps/{appId}/marketing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": { "type": "string", "minLength": 130, "maxLength": 200 }, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroMedia": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false }, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": { "type": "string", "enum": [ "active", "preview", "platform", "community" ] }, "subcategory": { "type": "string" }, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "marketplaceCategory": { "type": "string" }, "stageLabel": { "type": "string" }, "surface": { "type": "string" }, "shortBlurb": { "type": "string" }, "tagline": { "type": "string" }, "problemStatement": { "type": "string" }, "solutionStatement": { "type": "string" }, "docsUrl": { "type": "string" }, "appUrl": { "type": "string" }, "gallery": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false } }, "benefits": {}, "features": {}, "stats": {}, "gettingStarted": {}, "worksWellWith": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/apps/{appId}/marketing. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.mobile_artifacts.list Execute apps.mobile_artifacts.list in Topolo Developers. Contract: GET /api/developer-console/apps/{appId}/mobile-artifacts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/apps/{appId}/mobile-artifacts without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.mobile_artifacts.create Execute apps.mobile_artifacts.create in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/mobile-artifacts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "platform": "android", "versionName": "example", "artifactType": "metadata" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "platform": { "type": "string", "enum": [ "android", "ios" ] }, "releaseTrack": { "type": "string", "minLength": 1, "maxLength": 60 }, "packageName": { "type": "string", "minLength": 1 }, "bundleId": { "type": "string", "minLength": 1 }, "versionName": { "type": "string", "minLength": 1, "maxLength": 40 }, "buildNumber": { "type": "string", "minLength": 1, "maxLength": 40 }, "artifactType": { "type": "string", "enum": [ "metadata", "apk", "aab", "ipa", "app_store", "testflight" ] }, "artifactUrl": { "type": "string", "format": "uri" }, "checksumSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "type": "string", "enum": [ "draft", "submitted", "approved", "published", "retired" ] }, "minimumOsVersion": { "type": "string", "minLength": 1, "maxLength": 40 }, "supportedDeviceClasses": { "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1 } }, "distributionChannel": { "type": "string", "minLength": 1, "maxLength": 60 }, "catalogCategory": { "type": "string", "enum": [ "system-apps", "topolo-store", "topolo-apps", "apkList" ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "appId", "platform", "versionName", "artifactType" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/mobile-artifacts. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.native_mobile_experience.update Execute apps.native_mobile_experience.update in Topolo Developers. Contract: PUT /api/developer-console/apps/{appId}/native-mobile-experience Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/apps/{appId}/native-mobile-experience. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.native_mobile_experience.delete Execute apps.native_mobile_experience.delete in Topolo Developers. Contract: DELETE /api/developer-console/apps/{appId}/native-mobile-experience Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-console/apps/{appId}/native-mobile-experience. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.actions.list Execute apps.actions.list in Topolo Developers. Contract: GET /api/developer-console/apps/{appId}/actions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/apps/{appId}/actions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.actions.create Execute apps.actions.create in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/actions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/actions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.actions.publish Execute apps.actions.publish in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/actions/{actionId}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "actionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": { "type": "string", "minLength": 1 }, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId", "actionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/actions/{actionId}/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.api_key_resources.list Execute apps.api_key_resources.list in Topolo Developers. Contract: GET /api/developer-console/apps/{appId}/api-key-resources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/apps/{appId}/api-key-resources without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.api_key_resources.update Execute apps.api_key_resources.update in Topolo Developers. Contract: PUT /api/developer-console/apps/{appId}/api-key-resources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/apps/{appId}/api-key-resources. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.api_key_resources.publish Execute apps.api_key_resources.publish in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/api-key-resources/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/api-key-resources/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.p2p_capabilities.list Execute apps.p2p_capabilities.list in Topolo Developers. Contract: GET /api/developer-console/apps/{appId}/p2p-capabilities Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/apps/{appId}/p2p-capabilities without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.p2p_capabilities.create Execute apps.p2p_capabilities.create in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/p2p-capabilities Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "pricingModel": {}, "pricingAmountMinor": {}, "currency": {}, "supportedContexts": {}, "trustLevel": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/p2p-capabilities. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.p2p_capabilities.update Execute apps.p2p_capabilities.update in Topolo Developers. Contract: PUT /api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "capabilityId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": { "type": "string", "minLength": 1 }, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "pricingModel": {}, "pricingAmountMinor": {}, "currency": {}, "supportedContexts": {}, "trustLevel": {} }, "required": [ "appId", "capabilityId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.p2p_capabilities.sync Execute apps.p2p_capabilities.sync in Topolo Developers. Contract: POST /api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId}/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "capabilityId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": { "type": "string", "minLength": 1 }, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId", "capabilityId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/apps/{appId}/p2p-capabilities/{capabilityId}/sync. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### review.build_requests.list Execute review.build_requests.list in Topolo Developers. Contract: GET /api/developer-console/review/build-requests Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: review:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/review/build-requests without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### review.build_requests.review Execute review.build_requests.review in Topolo Developers. Contract: POST /api/developer-console/review/build-requests/{requestId}/review Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: review:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "requestId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": { "type": "string", "minLength": 1 }, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "requestId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/review/build-requests/{requestId}/review. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.marketplace.summary.get Execute admin.marketplace.summary.get in Topolo Developers. Contract: GET /api/developer-console/admin/marketplace/summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:read Agent access: off; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "developersCursor": "example", "appsCursor": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "developersCursor": { "type": "string" }, "appsCursor": { "type": "string" }, "payoutAccountsCursor": { "type": "string" }, "payoutEventsCursor": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/admin/marketplace/summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.developers.update Execute admin.developers.update in Topolo Developers. Contract: PUT /api/developer-console/admin/developers/{developerId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "developerId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": { "type": "string", "minLength": 1 }, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "reviewState": {} }, "required": [ "developerId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/admin/developers/{developerId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.platform_app_scaffolds.create Execute admin.platform_app_scaffolds.create in Topolo Developers. Contract: POST /api/developer-console/admin/platform-app-scaffolds Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/admin/platform-app-scaffolds. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.first_party_app_scaffolds.create Execute admin.first_party_app_scaffolds.create in Topolo Developers. Contract: POST /api/developer-console/admin/first-party-app-scaffolds Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/admin/first-party-app-scaffolds. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.apps.reconcile Check or apply a declarative first-party application registration and its catalog and Auth projections. Contract: POST /api/developer-console/admin/apps/reconcile Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "mode": { "type": "string", "enum": [ "check", "apply" ] }, "healthcheckPath": {}, "callbackUrls": { "type": "array", "items": { "type": "string" } }, "requestedScopes": { "type": "array", "items": { "type": "string" } }, "capabilities": { "type": "array", "items": { "type": "string" } }, "marketplace": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "notifications": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "actions": { "type": "array", "maxItems": 250, "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/admin/apps/reconcile. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.apps.catalog_projection.delete Archive an exactly matched orphan developer application when explicitly requested, then permanently remove its public catalog directory row and per-app manifest partition. Contract: DELETE /api/developer-console/admin/apps/{appId}/catalog-projection Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: off; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "example", "expectedSlug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "expectedSlug": { "type": "string", "minLength": 1 }, "archiveActive": { "description": "Must be true to archive a matching active developer application before its public catalog projection is removed.", "type": "boolean" } }, "required": [ "appId", "expectedSlug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-console/admin/apps/{appId}/catalog-projection. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.apps.marketing.update Execute admin.apps.marketing.update in Topolo Developers. Contract: PUT /api/developer-console/admin/apps/{appId}/marketing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": { "type": "string", "minLength": 130, "maxLength": 200 }, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroMedia": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false }, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": { "type": "string", "enum": [ "active", "preview", "platform", "community" ] }, "subcategory": { "type": "string" }, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "marketplaceCategory": { "type": "string" }, "stageLabel": { "type": "string" }, "surface": { "type": "string" }, "shortBlurb": { "type": "string" }, "tagline": { "type": "string" }, "problemStatement": { "type": "string" }, "solutionStatement": { "type": "string" }, "docsUrl": { "type": "string" }, "appUrl": { "type": "string" }, "gallery": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "image", "video" ] }, "src": { "type": "string", "format": "uri" }, "alt": { "type": "string", "minLength": 1, "maxLength": 240 }, "poster": { "type": "string", "format": "uri" }, "caption": { "type": "string", "maxLength": 400 } }, "required": [ "type", "src", "alt" ], "additionalProperties": false } }, "benefits": {}, "features": {}, "stats": {}, "gettingStarted": {}, "worksWellWith": {} }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/admin/apps/{appId}/marketing. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.apps.marketplace.update Execute admin.apps.marketplace.update in Topolo Developers. Contract: PUT /api/developer-console/admin/apps/{appId}/marketplace Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": { "anyOf": [ { "type": "number" }, { "type": "string", "const": "" }, { "type": "null" } ] }, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": { "type": "string", "enum": [ "included", "free", "paid", "request", "external" ] }, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "billingInterval": { "type": "string", "enum": [ "monthly", "annual", "one_time" ] }, "priceLabel": { "type": "string", "maxLength": 80 }, "catalogListingState": { "type": "string", "enum": [ "draft", "developer_only", "internal", "unlisted", "public", "retired" ] }, "runtimeState": { "type": "string", "enum": [ "healthy", "disabled", "sunset" ] }, "checkoutStatus": { "type": "string", "enum": [ "not_configured", "ready", "blocked" ] }, "platformFeeBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/admin/apps/{appId}/marketplace. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.payout_accounts.update Execute admin.payout_accounts.update in Topolo Developers. Contract: PUT /api/developer-console/admin/payout-accounts/{developerId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "developerId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": { "type": "string", "minLength": 1 }, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "provider": {}, "accountReference": {}, "defaultCurrency": {}, "payoutSchedule": {} }, "required": [ "developerId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/admin/payout-accounts/{developerId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.payout_events.create Execute admin.payout_events.create in Topolo Developers. Contract: POST /api/developer-console/admin/payout-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {}, "eventType": {}, "amount": {}, "currency": {} }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/admin/payout-events. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.catalog.get Execute admin.catalog.get in Topolo Developers. Contract: GET /api/developer-console/admin/catalog Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:read Agent access: off; read-only: true; destructive: false; confirmation: false Example input: ```json { "resource": "collections", "cursor": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resource": { "type": "string", "enum": [ "collections", "apps" ] }, "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "query": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/admin/catalog without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.catalog.collections.create Execute admin.catalog.collections.create in Topolo Developers. Contract: POST /api/developer-console/admin/catalog/collections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "action": "example", "apiKeyResources": "example", "appDir": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": {}, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/admin/catalog/collections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.catalog.collections.update Execute admin.catalog.collections.update in Topolo Developers. Contract: PUT /api/developer-console/admin/catalog/collections/{collectionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "collectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": { "type": "string", "minLength": 1 }, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "collectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/developer-console/admin/catalog/collections/{collectionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.catalog.collections.apps.list Execute admin.catalog.collections.apps.list in Topolo Developers. Contract: GET /api/developer-console/admin/catalog/collections/{collectionId}/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:read Agent access: off; read-only: true; destructive: false; confirmation: false Example input: ```json { "collectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "collectionId": { "type": "string", "minLength": 1 }, "cursor": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "query": { "type": "string" } }, "required": [ "collectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/admin/catalog/collections/{collectionId}/apps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.catalog.collections.apps.add Execute admin.catalog.collections.apps.add in Topolo Developers. Contract: POST /api/developer-console/admin/catalog/collections/{collectionId}/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: false; confirmation: true Example input: ```json { "collectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": {}, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": { "type": "string", "minLength": 1 }, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "collectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-console/admin/catalog/collections/{collectionId}/apps. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.catalog.collections.apps.remove Execute admin.catalog.collections.apps.remove in Topolo Developers. Contract: DELETE /api/developer-console/admin/catalog/collections/{collectionId}/apps/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: marketplace:write Agent access: off; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "example", "collectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": {}, "apiKeyResources": {}, "appDir": {}, "appId": { "type": "string", "minLength": 1 }, "appIdea": {}, "appStatus": {}, "applicationId": {}, "audience": {}, "budgetContext": {}, "category": {}, "communityBenefitIdea": {}, "companyName": {}, "companySpecificNeeds": {}, "containerAppId": {}, "demoUrl": {}, "description": {}, "descriptor": {}, "distributionModel": {}, "eyebrow": {}, "featured": {}, "firstAppCategory": {}, "firstAppName": {}, "heroImage": {}, "heroMedia": {}, "id": {}, "impact": {}, "intent": {}, "launcherQuickLinks": {}, "location": {}, "members": {}, "mobileExperience": {}, "monthlyPrice": {}, "name": {}, "notes": {}, "onboardingConfirmed": {}, "onboardingState": {}, "onboardingStep": {}, "operationalContactEmail": {}, "operationalContactName": {}, "ownerType": {}, "packageName": {}, "planPreference": {}, "portfolio": {}, "pricingType": {}, "productionUrl": {}, "rejectionReason": {}, "repoUrl": {}, "requestType": {}, "resources": {}, "reviewNotes": {}, "screenshots": {}, "serviceSlug": {}, "slug": {}, "sortOrder": {}, "source": {}, "status": {}, "subcategory": {}, "summary": {}, "supportEmail": {}, "surfaceModel": {}, "tags": {}, "tenancy": {}, "title": {}, "transferCode": {}, "useCase": {}, "version": {}, "websiteUrl": {}, "actionId": {}, "capabilityId": {}, "collectionId": { "type": "string", "minLength": 1 }, "developerId": {}, "requestId": {}, "submissionId": {}, "inputSchema": {}, "outputSchema": {}, "method": {}, "path": {}, "permission": {}, "readOnly": {}, "destructive": {}, "requiresConfirmation": {}, "agentAccess": {} }, "required": [ "appId", "collectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-console/admin/catalog/collections/{collectionId}/apps/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.data.export Export the selected workspace data owned by Topolo Developers with credential fields redacted. Contract: GET /api/developer-console/workspaces/{workspaceId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-console/workspaces/{workspaceId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.data.erase Permanently erase the selected workspace data and derived projections owned by Topolo Developers. Contract: DELETE /api/developer-console/workspaces/{workspaceId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-console/workspaces/{workspaceId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Manage app-local workspaces in Topolo Developers. Contract: DELETE /api/developer-console/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-console/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo Device Platform source contract Human reference: https://docs.topolo.app/systems/topolo-device-platform Machine reference: https://docs.topolo.app/machine/systems/topolo-device-platform.json Source revisions: apps/TopoloFeed@deab96cb4917fd854dbd9f87e2bf944b242ce2c5 Deploy targets: 3; implemented actions: 14; declared actions: 14; uncatalogued served routes: 0; mobile contracts: 1; route signals: 25. ### widget.get Get the TopoloOne widget summary for Feed. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: feed:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get widget summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.summary.get Summarize impressions for the active Feed workspace and optional time range. Contract: GET /api/analytics/summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000", "start_time": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "start_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ad_id_pattern": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get feed analytics summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/analytics/summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.engagement.get Get completion, interaction, and duration metrics for the active Feed workspace. Contract: GET /api/analytics/engagement Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000", "start_time": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "start_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "end_time": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "ad_id_pattern": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get feed engagement.", "additionalProperties": true } ``` Effects: Reads state through GET /api/analytics/engagement without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.devices.list List devices observed in the active Feed workspace. Contract: GET /api/analytics/devices Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List feed devices.", "additionalProperties": true } ``` Effects: Reads state through GET /api/analytics/devices without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.delete Delete an empty non-default Feed workspace. Contract: DELETE /api/analytics/feed/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete feed workspace.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/analytics/feed/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### analytics.digest.generate Persist an engagement digest for the active Feed workspace and emit its ready event. Contract: POST /api/analytics/digests Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: feed:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "windowStart": 1, "windowEnd": 2 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "windowStart": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "windowEnd": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "windowStart", "windowEnd" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate feed digest.", "additionalProperties": true } ``` Effects: Creates a workspace-scoped engagement digest and emits the feed.digest.ready notification event. Verification: Confirm the response contains $.digest.id for the selected reporting window. Recovery: 400 invalid_reporting_window: Choose a windowEnd greater than windowStart and retry. 403 forbidden: Use a credential with feed:write access to the selected Feed workspace. ### analytics.anomaly.check Evaluate a completion-rate threshold and persist a detected workspace anomaly. Contract: POST /api/analytics/anomaly-checks Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: feed:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "windowStart": 1, "windowEnd": 2, "minimumCompletionRate": 75 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "windowStart": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "windowEnd": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "minimumCompletionRate": { "type": "number", "minimum": 0, "maximum": 100 } }, "required": [ "windowStart", "windowEnd", "minimumCompletionRate" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Check feed engagement anomaly.", "additionalProperties": true } ``` Effects: Evaluates the workspace completion rate and persists an anomaly when it is below minimumCompletionRate. Verification: Confirm $.observedValue is present and, when below the threshold, $.anomaly.id identifies the persisted anomaly. Recovery: 400 invalid_reporting_window: Choose a windowEnd greater than windowStart and retry. 403 forbidden: Use a credential with feed:write access to the selected Feed workspace. ### devices.credential.rotate Issue a new one-time credential for a device in the active Feed workspace and invalidate its previous credential. Contract: POST /api/analytics/devices/{deviceId}/credential Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: feed:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Rotate feed device credential.", "additionalProperties": true } ``` Effects: May change state through POST /api/analytics/devices/{deviceId}/credential. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sources.list List registered content sources in the active Feed workspace. Contract: GET /api/analytics/sources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: feed:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "workspace_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List feed sources.", "additionalProperties": true } ``` Effects: Reads state through GET /api/analytics/sources without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sources.create Register an HTTPS content source in the active Feed workspace. Contract: POST /api/analytics/sources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: feed:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "endpointUrl": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "endpointUrl": { "type": "string", "format": "uri", "pattern": "^https:\\/\\/.*" } }, "required": [ "name", "endpointUrl" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create feed source.", "additionalProperties": true } ``` Effects: May change state through POST /api/analytics/sources. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### privacy.export Export all Feed records for the authenticated organization with protected fields decrypted for the requester. Contract: GET /api/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Export Feed organization data.", "additionalProperties": true } ``` Effects: Reads state through GET /api/privacy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.delete Permanently erase Feed records for the authenticated organization and retain only a hashed erasure receipt. Contract: DELETE /api/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Erase Feed organization data.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/privacy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### privacy.protection.canary Verify protected Feed D1 and KV fields decrypt and report any remaining plaintext records. Contract: GET /api/privacy/protection/canary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Check Feed data protection.", "additionalProperties": true } ``` Effects: Reads state through GET /api/privacy/protection/canary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sources.sync Refresh one registered Feed source and persist its terminal sync result. Contract: POST /api/analytics/sources/{sourceId}/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: feed:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "sourceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sourceId": { "type": "string", "minLength": 1 } }, "required": [ "sourceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sync feed source.", "additionalProperties": true } ``` Effects: May change state through POST /api/analytics/sources/{sourceId}/sync. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo Forecast source contract Human reference: https://docs.topolo.app/systems/topolo-forecast Machine reference: https://docs.topolo.app/machine/systems/topolo-forecast.json Source revisions: apps/TopoloForecast@e1e2cb0fb630c8da1d3fc157c568b6ec072ccc7a Deploy targets: 2; implemented actions: 52; declared actions: 52; uncatalogued served routes: 0; mobile contracts: 1; route signals: 80. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### coa.get Get Forecast chart of accounts. Contract: GET /api/v1/{workspace}/coa Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get chart of accounts.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/coa without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.set_active_scenario Set the active Forecast workspace scenario. Contract: PATCH /api/v1/workspaces/{id}/active-scenario Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "scenarioId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 } }, "required": [ "id", "scenarioId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set active scenario.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/workspaces/{id}/active-scenario. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Delete a Forecast workspace. Contract: DELETE /api/v1/workspaces/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete workspace.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/workspaces/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace_shares.list List Forecast workspace shares. Contract: GET /api/v1/workspaces/{workspaceId}/shares Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List workspace shares.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/workspaces/{workspaceId}/shares without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace_shares.create Create a Forecast workspace share. Contract: POST /api/v1/workspaces/{workspaceId}/shares Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recipient_user_id": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create workspace share.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/workspaces/{workspaceId}/shares. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace_shares.update Update a Forecast workspace share. Contract: PATCH /api/v1/workspaces/{workspaceId}/shares/{shareId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "shareId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspaceId", "shareId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update workspace share.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/workspaces/{workspaceId}/shares/{shareId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace_shares.delete Delete a Forecast workspace share. Contract: DELETE /api/v1/workspaces/{workspaceId}/shares/{shareId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example", "shareId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "shareId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete workspace share.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/workspaces/{workspaceId}/shares/{shareId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### share_settings.get Get Forecast workspace share settings. Contract: GET /api/v1/workspaces/{workspaceId}/share-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get share settings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/workspaces/{workspaceId}/share-settings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### share_settings.update Update Forecast workspace share settings. Contract: PATCH /api/v1/workspaces/{workspaceId}/share-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "sharing_enabled": { "type": "boolean" }, "default_permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "default_expiry_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_active_shares": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "require_password": { "type": "boolean" }, "allowed_domains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "custom_branding_enabled": { "type": "boolean" }, "custom_logo_url": { "type": "string", "minLength": 1 }, "custom_title": { "type": "string", "minLength": 1 }, "custom_description": { "type": "string", "minLength": 1 }, "analytics_enabled": { "type": "boolean" } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update share settings.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/workspaces/{workspaceId}/share-settings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### scenarios.list List Forecast scenarios. Contract: GET /api/v1/{workspace}/scenarios Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List scenarios.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/scenarios without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### scenarios.create Create a Forecast scenario in a platform-authorized workspace, including the first scenario for a newly created workspace. Contract: POST /api/v1/{workspace}/scenarios Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "ws_forecast_northstar", "name": "Northstar FY27 Base Plan" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_scenario_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "workspace", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Created Forecast scenario.", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "workspace_id" ], "additionalProperties": true }, "message": { "type": "string" } }, "required": [ "success", "data" ], "additionalProperties": true } ``` Effects: Creates a planning scenario in the selected platform-authorized Forecast workspace. This is the bootstrap action for a newly created workspace. Verification: Call scenarios.list with the same workspace and confirm the returned list contains $.data.id and the requested name. Recovery: [object Object] 403 action_permission_required: Use a credential with forecasts:write access to the selected Forecast workspace. ### scenarios.update Update a Forecast scenario. Contract: PATCH /api/v1/{workspace}/scenarios/{scenarioId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "scenarioId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "archived": { "type": "boolean" } }, "required": [ "workspace", "scenarioId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update scenario.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/{workspace}/scenarios/{scenarioId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### scenarios.duplicate Duplicate a Forecast scenario. Contract: POST /api/v1/{workspace}/scenarios/{scenarioId}/duplicate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "scenarioId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "scenarioId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Duplicate scenario.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/scenarios/{scenarioId}/duplicate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### scenarios.delete Delete a Forecast scenario. Contract: DELETE /api/v1/{workspace}/scenarios/{scenarioId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspace": "example", "scenarioId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "scenarioId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete scenario.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/{workspace}/scenarios/{scenarioId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### coa.create Create a Forecast chart of accounts entry. Contract: POST /api/v1/{workspace}/coa Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "name": "example", "type": "income" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "income", "cos", "opex", "calc" ] }, "trend_factor": { "type": "number" }, "parentId": { "type": "string", "minLength": 1 }, "order_index": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "name", "type" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create chart account.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/coa. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### coa.update Update a Forecast chart of accounts entry. Contract: PATCH /api/v1/{workspace}/coa/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "income", "cos", "opex", "calc" ] }, "trend_factor": { "type": "number", "minimum": -10, "maximum": 10 }, "parentId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update chart account.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/{workspace}/coa/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### coa.delete Delete a Forecast chart of accounts entry. Contract: DELETE /api/v1/{workspace}/coa/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspace": "example", "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "force": { "type": "boolean" } }, "required": [ "workspace", "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete chart account.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/{workspace}/coa/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### daily.get Get Forecast daily entries for a period. Contract: GET /api/v1/{workspace}/daily/{period} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example", "period": "2026-01" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get daily entries.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/daily/{period} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### daily.annual.get Get Forecast daily entries for a year. Contract: GET /api/v1/{workspace}/daily/annual/{year} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example", "year": "2026" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "year": { "type": "string", "pattern": "^\\d{4}$" } }, "required": [ "workspace", "year" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get annual daily entries.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/daily/annual/{year} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### daily.upsert Upsert a Forecast daily entry. Contract: PUT /api/v1/{workspace}/daily Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "coaId": "example", "date": "2026-01-01", "amountCents": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "coaId": { "type": "string", "minLength": 1 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActual": { "type": "boolean" }, "note": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "coaId", "date", "amountCents" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Upsert daily entry.", "additionalProperties": true } ``` Effects: May change state through PUT /api/v1/{workspace}/daily. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### daily.bulk_upsert Bulk upsert Forecast daily entries. Contract: PUT /api/v1/{workspace}/daily/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "operating-plan", "entries": [ { "coaId": "account-revenue", "date": "2026-10-01", "amountCents": 6500000, "isActual": false, "note": "Base-case monthly forecast" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entries": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "coaId": { "type": "string", "minLength": 1 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActual": { "type": "boolean" }, "note": { "type": "string", "minLength": 1 } }, "required": [ "coaId", "date", "amountCents" ], "additionalProperties": false } } }, "required": [ "workspace", "entries" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk upsert daily entries.", "additionalProperties": true } ``` Effects: Creates or replaces up to 100 Forecast daily entries in the workspace's active scenario, keyed by chart-of-account id and date. Verification: Call daily.annual.get for every affected year in the same workspace and compare each submitted chart-of-account id, date, amountCents, isActual, and note. Recovery: 500 BULK_DAILY_ENTRY_SAVE_ERROR: Preserve the submitted entries and request id, then retry only after the Forecast service reports healthy; entries already written remain upsert-safe by workspace, scenario, chart-of-account id, and date. ### imports.run Persist a bounded batch of Forecast entries and its terminal import result. Contract: POST /api/v1/{workspace}/imports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "entries": [ { "coaId": "example", "date": "2026-01-01", "amountCents": 1 } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entries": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "coaId": { "type": "string", "minLength": 1 }, "date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amountCents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "isActual": { "type": "boolean" }, "note": { "type": "string", "minLength": 1 } }, "required": [ "coaId", "date", "amountCents" ], "additionalProperties": false } } }, "required": [ "workspace", "entries" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Import forecast entries.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/imports. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### summary.month.get Get Forecast monthly summary. Contract: GET /api/v1/{workspace}/summary/month/{period} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example", "period": "2026-01" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get monthly summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/summary/month/{period} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### summary.year.get Get Forecast yearly summary. Contract: GET /api/v1/{workspace}/summary/year/{period} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example", "period": "2026" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get yearly summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/summary/year/{period} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### forecast.get Get Forecast projection for a period. Contract: GET /api/v1/{workspace}/forecast/{period} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example", "period": "2026-01" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "depth": { "type": "integer", "minimum": 1, "maximum": 36 } }, "required": [ "workspace", "period" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get forecast.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/forecast/{period} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### openclaw.events.list List Forecast OpenClaw events. Contract: GET /api/v1/{workspace}/openclaw/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "since": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List OpenClaw events.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/openclaw/events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### openclaw.forecast_health.get Get Forecast OpenClaw health. Contract: GET /api/v1/{workspace}/openclaw/forecast-health Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "depth": { "type": "integer", "minimum": 1, "maximum": 36 }, "stale_after_hours": { "type": "integer", "minimum": 1, "maximum": 720 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get forecast health.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/openclaw/forecast-health without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### openclaw.report_status.create Create Forecast OpenClaw report status. Contract: POST /api/v1/{workspace}/openclaw/report-status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "name": "example", "status": "queued" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "stale" ] }, "runId": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "period": { "type": "string", "minLength": 1 }, "format": { "type": "string", "minLength": 1 }, "scheduledFor": { "type": "string", "minLength": 1 }, "startedAt": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "minLength": 1 }, "artifactUrl": { "type": "string", "minLength": 1 }, "error": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "workspace", "name", "status" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create report status.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/openclaw/report-status. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### openclaw.export_status.create Create Forecast OpenClaw export status. Contract: POST /api/v1/{workspace}/openclaw/export-status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "name": "example", "status": "queued" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "running", "succeeded", "failed", "stale" ] }, "runId": { "type": "string", "minLength": 1 }, "scenarioId": { "type": "string", "minLength": 1 }, "period": { "type": "string", "minLength": 1 }, "format": { "type": "string", "minLength": 1 }, "scheduledFor": { "type": "string", "minLength": 1 }, "startedAt": { "type": "string", "minLength": 1 }, "completedAt": { "type": "string", "minLength": 1 }, "artifactUrl": { "type": "string", "minLength": 1 }, "error": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "workspace", "name", "status" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create export status.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/openclaw/export-status. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### cash_accounts.list List Forecast cash accounts. Contract: GET /api/v1/{workspace}/cash-accounts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List cash accounts.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/cash-accounts without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### cash_accounts.create Create a workspace-level Forecast cash account. A scenario is not required. Contract: POST /api/v1/{workspace}/cash-accounts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "ws_forecast_northstar", "account_name": "Northstar Operating Account", "account_type": "checking", "starting_balance_cents": 1850000, "display_order": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "account_name": { "type": "string", "minLength": 1 }, "account_type": { "type": "string", "enum": [ "checking", "savings", "investment", "cash", "credit_card", "other" ] }, "starting_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "account_name", "account_type" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Created Forecast cash account.", "properties": { "success": { "type": "boolean" }, "data": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "account_name": { "type": "string", "minLength": 1 }, "account_type": { "type": "string" } }, "required": [ "id", "workspace_id", "account_name", "account_type" ], "additionalProperties": true } }, "required": [ "success", "data" ], "additionalProperties": true } ``` Effects: Creates a workspace-level cash account and initializes its current balance from starting_balance_cents. Verification: Call cash_accounts.list with the same workspace and confirm the returned list contains $.data.id, account_name, account_type, and starting balance. Recovery: [object Object] 403 action_permission_required: Use a credential with settings:write access to the selected Forecast workspace. ### cash_accounts.update Update a Forecast cash account. Contract: PATCH /api/v1/{workspace}/cash-accounts/{accountId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "accountId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "minLength": 1 }, "account_name": { "type": "string", "minLength": 1 }, "account_type": { "type": "string", "enum": [ "checking", "savings", "investment", "cash", "credit_card", "other" ] }, "starting_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "current_balance_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "is_active": { "type": "boolean" }, "display_order": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "accountId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update cash account.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/{workspace}/cash-accounts/{accountId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### cash_accounts.delete Delete a Forecast cash account. Contract: DELETE /api/v1/{workspace}/cash-accounts/{accountId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspace": "example", "accountId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "accountId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete cash account.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/{workspace}/cash-accounts/{accountId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### cash_flow.get Get Forecast cash flow for a period. Contract: GET /api/v1/{workspace}/cash-flow/{period} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example", "period": "2026-01" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "period": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" } }, "required": [ "workspace", "period" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get cash flow.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/cash-flow/{period} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### cash_flow.create Create a Forecast cash flow entry. Contract: POST /api/v1/{workspace}/cash-flow Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "cash_account_id": "00000000-0000-4000-8000-000000000000", "entry_date": "2026-01-01", "amount_cents": 1, "category": "revenue" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "cash_account_id": { "type": "string", "minLength": 1 }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "revenue", "expense", "transfer", "adjustment", "starting_balance" ] }, "p_and_l_account_id": { "type": "string", "minLength": 1 }, "transfer_account_id": { "type": "string", "minLength": 1 }, "transfer_group_id": { "type": "string", "minLength": 1 }, "is_actual": { "type": "boolean" } }, "required": [ "workspace", "cash_account_id", "entry_date", "amount_cents", "category" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create cash flow entry.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/cash-flow. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### cash_flow.update Update a Forecast cash flow entry. Contract: PATCH /api/v1/{workspace}/cash-flow/{entryId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "entryId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entryId": { "type": "string", "minLength": 1 }, "entry_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "revenue", "expense", "transfer", "adjustment", "starting_balance" ] }, "p_and_l_account_id": { "type": "string", "minLength": 1 }, "transfer_account_id": { "type": "string", "minLength": 1 }, "transfer_group_id": { "type": "string", "minLength": 1 }, "is_actual": { "type": "boolean" } }, "required": [ "workspace", "entryId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update cash flow entry.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/{workspace}/cash-flow/{entryId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### cash_flow.delete Delete a Forecast cash flow entry. Contract: DELETE /api/v1/{workspace}/cash-flow/{entryId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspace": "example", "entryId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "entryId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "entryId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete cash flow entry.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/{workspace}/cash-flow/{entryId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### cash_settings.get Get Forecast cash settings. Contract: GET /api/v1/{workspace}/cash-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get cash settings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/cash-settings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### cash_settings.update Update Forecast cash settings. Contract: PATCH /api/v1/{workspace}/cash-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "low_cash_warning_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "critical_cash_warning_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "auto_generate_forecasts": { "type": "boolean" }, "workspace_profile": { "type": "string", "enum": [ "business", "personal" ] } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update cash settings.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/{workspace}/cash-settings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### schedule_rules.list List Forecast schedule rules. Contract: GET /api/v1/{workspace}/schedule-rules Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List schedule rules.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/schedule-rules without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### schedule_rules.create Create a Forecast schedule rule. Contract: POST /api/v1/{workspace}/schedule-rules Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "coa_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pattern_type": { "type": "string", "minLength": 1 }, "pattern_config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "is_active": { "type": "boolean" } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create schedule rule.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/schedule-rules. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### schedule_rules.update Update a Forecast schedule rule. Contract: PUT /api/v1/{workspace}/schedule-rules/{ruleId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "ruleId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "ruleId": { "type": "string", "minLength": 1 }, "scenario_id": { "type": "string", "minLength": 1 }, "coa_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "amount_cents": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "pattern_type": { "type": "string", "minLength": 1 }, "pattern_config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "start_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "end_date": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "is_active": { "type": "boolean" } }, "required": [ "workspace", "ruleId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update schedule rule.", "additionalProperties": true } ``` Effects: May change state through PUT /api/v1/{workspace}/schedule-rules/{ruleId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### schedule_rules.delete Delete a Forecast schedule rule. Contract: DELETE /api/v1/{workspace}/schedule-rules/{ruleId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspace": "example", "ruleId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "ruleId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "ruleId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete schedule rule.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/{workspace}/schedule-rules/{ruleId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### shares.list Call GET /api/v1/{workspace}/shares. Contract: GET /api/v1/{workspace}/shares Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/shares without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### shares.create Call POST /api/v1/{workspace}/shares. Contract: POST /api/v1/{workspace}/shares Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recipient_user_id": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/v1/{workspace}/shares. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### shares.update Call PATCH /api/v1/{workspace}/shares/{shareId}. Contract: PATCH /api/v1/{workspace}/shares/{shareId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example", "shareId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "is_active": { "type": "boolean" }, "expires_at": { "type": "string", "minLength": 1 }, "max_accesses": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "workspace", "shareId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/{workspace}/shares/{shareId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### shares.delete Call DELETE /api/v1/{workspace}/shares/{shareId}. Contract: DELETE /api/v1/{workspace}/shares/{shareId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: forecasts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspace": "example", "shareId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "shareId": { "type": "string", "minLength": 1 } }, "required": [ "workspace", "shareId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/v1/{workspace}/shares/{shareId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### shares.settings.get Call GET /api/v1/{workspace}/share-settings. Contract: GET /api/v1/{workspace}/share-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares Settings Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/v1/{workspace}/share-settings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### shares.settings.update Call PATCH /api/v1/{workspace}/share-settings. Contract: PATCH /api/v1/{workspace}/share-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace": { "type": "string", "minLength": 1 }, "sharing_enabled": { "type": "boolean" }, "default_permission_level": { "type": "string", "enum": [ "read", "collaborate" ] }, "default_expiry_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "max_active_shares": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "require_password": { "type": "boolean" }, "allowed_domains": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "custom_branding_enabled": { "type": "boolean" }, "custom_logo_url": { "type": "string", "minLength": 1 }, "custom_title": { "type": "string", "minLength": 1 }, "custom_description": { "type": "string", "minLength": 1 }, "analytics_enabled": { "type": "boolean" } }, "required": [ "workspace" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Shares Settings Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/v1/{workspace}/share-settings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.data.export Export all Forecast data owned by the authenticated organization without share credential material. Contract: GET /api/organizations/data/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/data/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Permanently erase all Forecast data and workspace-scoped caches owned by the authenticated organization while retaining backups under policy. Contract: DELETE /api/organizations/data/erase Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo MCP source contract Human reference: https://docs.topolo.app/systems/topolo-mcp Machine reference: https://docs.topolo.app/machine/systems/topolo-mcp.json Source revisions: topolo-platform/packages/topolo-mcp@515376de81efed9734741b2a1d691c8195243073 Deploy targets: 0; implemented actions: 0; declared actions: 0; uncatalogued served routes: 0; mobile contracts: 0; route signals: 0. ## Topolo Nexus source contract Human reference: https://docs.topolo.app/systems/topolo-nexus Machine reference: https://docs.topolo.app/machine/systems/topolo-nexus.json Source revisions: topolo-platform/services/TopoloNexus@515376de81efed9734741b2a1d691c8195243073 Deploy targets: 2; implemented actions: 77; declared actions: 77; uncatalogued served routes: 1; mobile contracts: 1; route signals: 85. ### widget.get Read GET /api/widget through Nexus. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Widget Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization.get Read GET /api/organization through Nexus. Contract: GET /api/organization Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Organization Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization.provision Invoke POST /api/organizations/provision through Nexus. Contract: POST /api/organizations/provision Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:provision Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organization_id": "org_demo", "name": "Demo Organization", "slug": "demo-organization" } ``` Input schema: ```json { "type": "object", "properties": { "organization_id": { "type": "string", "minLength": 1 }, "name": { "$ref": "#/properties/organization_id" }, "slug": { "$ref": "#/properties/organization_id" }, "billing_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] } }, "required": [ "organization_id", "name", "slug" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Organization Provision.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/provision. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### audit.list Read GET /api/audit through Nexus. Contract: GET /api/audit Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1 } ``` Input schema: ```json { "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Audit List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/audit without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.export Read GET /api/privacy through Nexus. Contract: GET /api/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: org:admin Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Privacy Export.", "additionalProperties": true } ``` Effects: Reads state through GET /api/privacy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.delete Erase all Nexus-owned data for the authenticated organization and retain only hash-based compliance evidence. Contract: DELETE /api/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: org:admin Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Privacy Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/privacy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.list Read GET /api/apps through Nexus. Contract: GET /api/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/apps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.get Read GET /api/apps/{appSlug} through Nexus. Contract: GET /api/apps/{appSlug} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appSlug": "example" } ``` Input schema: ```json { "type": "object", "properties": { "appSlug": { "type": "string", "minLength": 1 } }, "required": [ "appSlug" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/apps/{appSlug} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.update Invoke PATCH /api/apps/{appSlug} through Nexus. Contract: PATCH /api/apps/{appSlug} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appSlug": "example" } ``` Input schema: ```json { "type": "object", "properties": { "appSlug": { "type": "string", "minLength": 1 }, "enabled": { "type": "boolean" }, "custom_budget_cents": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "appSlug" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/apps/{appSlug}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.capabilities.list Read GET /api/apps/meta/capabilities through Nexus. Contract: GET /api/apps/meta/capabilities Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps Capabilities List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/apps/meta/capabilities without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.models.list Read GET /api/apps/meta/models through Nexus. Contract: GET /api/apps/meta/models Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps Models List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/apps/meta/models without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.overview Read GET /api/usage/overview through Nexus. Contract: GET /api/usage/overview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "start_date": "example", "end_date": "example" } ``` Input schema: ```json { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "$ref": "#/properties/start_date" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Overview.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/overview without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.daily Read GET /api/usage/daily through Nexus. Contract: GET /api/usage/daily Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 1 } ``` Input schema: ```json { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Daily.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/daily without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.by_app Read GET /api/usage/by-app through Nexus. Contract: GET /api/usage/by-app Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 1 } ``` Input schema: ```json { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage By App.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/by-app without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.by_user Read GET /api/usage/by-user through Nexus. Contract: GET /api/usage/by-user Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 1, "limit": 1, "app_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 }, "app_id": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage By User.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/by-user without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.by_model Read GET /api/usage/by-model through Nexus. Contract: GET /api/usage/by-model Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 1 } ``` Input schema: ```json { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage By Model.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/by-model without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.recent Read GET /api/usage/recent through Nexus. Contract: GET /api/usage/recent Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "app_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 }, "app_id": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Recent.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/recent without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.budget Read GET /api/usage/budget through Nexus. Contract: GET /api/usage/budget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Budget.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/budget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.budget.update Invoke PUT /api/usage/budget through Nexus. Contract: PUT /api/usage/budget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "monthly_budget_cents": 1 } ``` Input schema: ```json { "type": "object", "properties": { "monthly_budget_cents": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "monthly_budget_cents" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Budget Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/usage/budget. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### usage.projection Read GET /api/usage/projection through Nexus. Contract: GET /api/usage/projection Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Projection.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/projection without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.limits.list Read GET /api/usage/limits through Nexus. Contract: GET /api/usage/limits Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Limits List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/limits without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.limit_options.list Read GET /api/usage/limits/options through Nexus. Contract: GET /api/usage/limits/options Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Limit Options List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/limits/options without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.limits.update Invoke PUT /api/usage/limits through Nexus. Contract: PUT /api/usage/limits Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "scope_type": "organization", "scope_value": "example", "monthly_budget_cents": 1 } ``` Input schema: ```json { "type": "object", "properties": { "scope_type": { "type": "string", "enum": [ "organization", "app", "user", "capability", "use_case", "provider", "model", "platform" ] }, "scope_value": { "type": "string", "minLength": 1 }, "monthly_budget_cents": { "type": "integer", "minimum": 0 }, "hard_limit": { "type": "boolean" }, "is_active": { "type": "boolean" } }, "required": [ "scope_type", "scope_value", "monthly_budget_cents" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Limits Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/usage/limits. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### usage.spend.get Read GET /api/usage/spend through Nexus. Contract: GET /api/usage/spend Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "start_date": "example", "end_date": "example" } ``` Input schema: ```json { "type": "object", "properties": { "start_date": { "type": "string" }, "end_date": { "$ref": "#/properties/start_date" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Spend Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/spend without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.events.list Read GET /api/usage/events through Nexus. Contract: GET /api/usage/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "event_type": "example", "severity": "example" } ``` Input schema: ```json { "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 200 }, "event_type": { "type": "string" }, "severity": { "$ref": "#/properties/event_type" }, "since": { "$ref": "#/properties/event_type" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Events List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.key_health.get Read GET /api/usage/key-health through Nexus. Contract: GET /api/usage/key-health Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Key Health Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/key-health without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### usage.snapshots.daily Read GET /api/usage/snapshots/daily through Nexus. Contract: GET /api/usage/snapshots/daily Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "days": 1 } ``` Input schema: ```json { "type": "object", "properties": { "days": { "type": "integer", "exclusiveMinimum": 0, "maximum": 90 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Usage Snapshots Daily.", "additionalProperties": true } ``` Effects: Reads state through GET /api/usage/snapshots/daily without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.completions.create Invoke POST /api/ai/completions through Nexus. Contract: POST /api/ai/completions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "provider": "openai", "model": "example", "messages": [ { "role": "system" } ] } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "google", "xai", "cloudflare" ] }, "model": { "type": "string" }, "messages": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "system", "user", "assistant", "tool" ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "minItems": 1 }, { "type": "null" } ] }, "tool_call_id": { "$ref": "#/properties/model" }, "tool_calls": { "type": "array", "items": { "$ref": "#/properties/messages/items/properties/content/anyOf/1/items" } }, "name": { "$ref": "#/properties/model" } }, "required": [ "role" ], "additionalProperties": false } }, "prompt": { "$ref": "#/properties/model" }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 32000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 }, "stream": { "type": "boolean" }, "app_id": { "type": "string", "default": "unknown" }, "use_case": { "type": "string", "enum": [ "chat", "completion", "embedding", "image", "other" ], "default": "chat" }, "response_format": { "type": "object", "properties": { "type": { "type": "string", "const": "json_schema" }, "json_schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "strict": { "type": "boolean" }, "schema": {} }, "required": [ "name" ], "additionalProperties": false } }, "required": [ "type", "json_schema" ], "additionalProperties": false }, "tools": { "type": "array", "items": { "$ref": "#/properties/messages/items/properties/content/anyOf/1/items" } } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Completions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/completions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.translations.create Invoke POST /api/ai/translations through Nexus. Contract: POST /api/ai/translations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:translate Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "target_locale": "en-US", "texts": {} } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "anthropic", "google", "xai", "cloudflare" ] }, "model": { "type": "string" }, "source_locale": { "type": "string", "minLength": 2, "maxLength": 16, "default": "en" }, "target_locale": { "type": "string", "minLength": 2, "maxLength": 16 }, "namespace": { "type": "string", "minLength": 1, "maxLength": 80, "default": "common" }, "texts": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 4000 }, "propertyNames": { "minLength": 1 } }, "context": { "type": "string", "maxLength": 2000 }, "app_id": { "type": "string", "default": "unknown" }, "auto_publish": { "type": "boolean", "default": true } }, "required": [ "target_locale", "texts" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Translations Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/translations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.embeddings.create Invoke POST /api/ai/embeddings through Nexus. Contract: POST /api/ai/embeddings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "input": "example" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "model": { "type": "string" }, "input": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "items": { "$ref": "#/properties/input/anyOf/0" }, "minItems": 1, "maxItems": 64 } ] }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "input" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Embeddings Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/embeddings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.markdown.create Invoke POST /api/ai/markdown through Nexus. Contract: POST /api/ai/markdown Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "filename": "brief.txt", "data_base64": "SGVsbG8gVG9wb2xv" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "filename": { "type": "string", "minLength": 1 }, "data_base64": { "$ref": "#/properties/filename" }, "mime_type": { "type": "string" }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "filename", "data_base64" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Markdown Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/markdown. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.image.describe Invoke POST /api/ai/image/describe through Nexus. Contract: POST /api/ai/image/describe Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "filename": "campaign.png", "data_base64": "aW1hZ2U=" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "model": { "type": "string" }, "filename": { "type": "string", "minLength": 1 }, "data_base64": { "$ref": "#/properties/filename" }, "mime_type": { "$ref": "#/properties/model" }, "prompt": { "$ref": "#/properties/filename" }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 2048 }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "filename", "data_base64" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Image Describe.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/image/describe. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.autorag.search Invoke POST /api/ai/autorag/search through Nexus. Contract: POST /api/ai/autorag/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "instance": "topoloone-auto-rag", "query": "How do refunds work?" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "instance": { "type": "string", "minLength": 1 }, "query": { "$ref": "#/properties/instance" }, "max_num_results": { "type": "integer", "minimum": 1, "maximum": 20 }, "rewrite_query": { "type": "boolean" }, "ranking_options": { "type": "object", "properties": { "score_threshold": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "instance", "query" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Autorag Search.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/autorag/search. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.transcriptions.create Invoke POST /api/ai/transcriptions through Nexus. Contract: POST /api/ai/transcriptions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "provider": "cloudflare", "model": "example", "audioDataUrl": "https://example.com" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "const": "cloudflare" }, "model": { "type": "string" }, "audioDataUrl": { "type": "string", "minLength": 1 }, "audioBase64": { "$ref": "#/properties/audioDataUrl" }, "mime_type": { "$ref": "#/properties/model" }, "language": { "type": "string", "minLength": 2, "maxLength": 8 }, "initial_prompt": { "type": "string", "maxLength": 400 }, "duration_ms": { "type": "integer", "minimum": 0 }, "app_id": { "type": "string", "default": "unknown" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Transcriptions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/transcriptions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.generations.create Invoke POST /api/ai/generations through Nexus. Contract: POST /api/ai/generations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "operation": "image.generate" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "openai", "google", "xai", "cloudflare" ] }, "model": { "type": "string" }, "operation": { "type": "string", "enum": [ "image.generate", "video.generate", "video.poll", "audio.speech", "music.generate" ] }, "prompt": { "$ref": "#/properties/model" }, "negative_prompt": { "$ref": "#/properties/model" }, "candidate_count": { "type": "integer", "minimum": 1, "maximum": 4 }, "aspect_ratio": { "$ref": "#/properties/model" }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 30 }, "resolution": { "$ref": "#/properties/model" }, "quality": { "$ref": "#/properties/model" }, "width": { "type": "integer", "minimum": 64, "maximum": 4096 }, "height": { "type": "integer", "minimum": 64, "maximum": 4096 }, "seed": { "type": "integer", "minimum": 0, "maximum": 2147483647 }, "generate_audio": { "type": "boolean" }, "lyrics": { "type": "string", "minLength": 1, "maxLength": 3500 }, "lyrics_optimizer": { "type": "boolean" }, "is_instrumental": { "type": "boolean" }, "format": { "$ref": "#/properties/model" }, "sample_rate": { "type": "integer" }, "bitrate": { "type": "integer" }, "voice_id": { "$ref": "#/properties/model" }, "speaker": { "$ref": "#/properties/model" }, "speed": { "type": "number", "minimum": 0.5, "maximum": 2 }, "volume": { "type": "number", "minimum": 0, "maximum": 10 }, "pitch": { "type": "integer", "minimum": -12, "maximum": 12 }, "emotion": { "$ref": "#/properties/model" }, "external_job_id": { "$ref": "#/properties/model" }, "source_asset": { "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "mime_type": { "$ref": "#/properties/model" } }, "required": [ "url" ], "additionalProperties": false }, "app_id": { "type": "string", "default": "unknown" } }, "required": [ "operation" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Generations Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/ai/generations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ai.models.list Read GET /api/ai/models through Nexus. Contract: GET /api/ai/models Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Models List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/models without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### ai.provider_health.get Read GET /api/ai/health/{provider} through Nexus. Contract: GET /api/ai/health/{provider} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ai:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "provider": "example" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1 } }, "required": [ "provider" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ai Provider Health Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ai/health/{provider} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### provider_credentials.list Read GET /api/provider-credentials through Nexus. Contract: GET /api/provider-credentials Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: provider_credentials:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Provider Credentials List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/provider-credentials without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### provider_credentials.upsert Invoke PUT /api/provider-credentials/{provider} through Nexus. Contract: PUT /api/provider-credentials/{provider} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: provider_credentials:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "provider": "example", "secret": "examplexxx" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1 }, "secret": { "type": "string", "minLength": 10 } }, "required": [ "provider", "secret" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Provider Credentials Upsert.", "additionalProperties": true } ``` Effects: May change state through PUT /api/provider-credentials/{provider}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### provider_credentials.update Invoke PATCH /api/provider-credentials/{provider} through Nexus. Contract: PATCH /api/provider-credentials/{provider} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: provider_credentials:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "provider": "example", "is_active": true } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "minLength": 1 }, "is_active": { "type": "boolean" } }, "required": [ "provider", "is_active" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Provider Credentials Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/provider-credentials/{provider}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### preferences.list Read GET /api/preferences through Nexus. Contract: GET /api/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: preferences:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preferences List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/preferences without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### preferences.get Read GET /api/preferences/{useCase} through Nexus. Contract: GET /api/preferences/{useCase} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: preferences:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "useCase": "example" } ``` Input schema: ```json { "type": "object", "properties": { "useCase": { "type": "string", "minLength": 1 } }, "required": [ "useCase" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preferences Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/preferences/{useCase} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### preferences.set Invoke PUT /api/preferences/{useCase} through Nexus. Contract: PUT /api/preferences/{useCase} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: preferences:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "useCase": "example", "preferred_provider": "openai", "preferred_model": "example" } ``` Input schema: ```json { "type": "object", "properties": { "useCase": { "type": "string", "minLength": 1 }, "preferred_provider": { "type": "string", "enum": [ "openai", "anthropic", "google", "xai", "cloudflare" ] }, "preferred_model": { "type": "string" }, "fallback_provider": { "anyOf": [ { "$ref": "#/properties/preferred_provider" }, { "type": "null" } ] }, "fallback_model": { "type": [ "string", "null" ] }, "max_tokens": { "type": "integer", "minimum": 1, "maximum": 32000 }, "temperature": { "type": "number", "minimum": 0, "maximum": 2 } }, "required": [ "useCase", "preferred_provider", "preferred_model" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preferences Set.", "additionalProperties": true } ``` Effects: May change state through PUT /api/preferences/{useCase}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### preferences.delete Invoke DELETE /api/preferences/{useCase} through Nexus. Contract: DELETE /api/preferences/{useCase} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: preferences:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "useCase": "example" } ``` Input schema: ```json { "type": "object", "properties": { "useCase": { "type": "string", "minLength": 1 } }, "required": [ "useCase" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preferences Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/preferences/{useCase}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### preferences.available_models.list Read GET /api/preferences/available/models through Nexus. Contract: GET /api/preferences/available/models Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: preferences:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preferences Available Models List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/preferences/available/models without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### models.governance.get Read GET /api/models/governance through Nexus. Contract: GET /api/models/governance Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: models:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Models Governance Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/models/governance without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### models.sync Invoke POST /api/models/sync through Nexus. Contract: POST /api/models/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: models:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "provider": "example" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Models Sync.", "additionalProperties": true } ``` Effects: May change state through POST /api/models/sync. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### email.connections.list Read GET /api/email/connections through Nexus. Contract: GET /api/email/connections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: email:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Email Connections List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/email/connections without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### email.connections.create Invoke POST /api/email/connections through Nexus. Contract: POST /api/email/connections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: email:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "provider": "resend", "connection_name": "example", "sending_domain": "example" } ``` Input schema: ```json { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "resend", "cloudflare_email" ] }, "connection_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "sending_domain": { "type": "string", "minLength": 3, "maxLength": 255 }, "default_from_name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "default_reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] } }, "required": [ "provider", "connection_name", "sending_domain" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Email Connections Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/email/connections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### email.connections.update Invoke PATCH /api/email/connections/{id} through Nexus. Contract: PATCH /api/email/connections/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: email:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "connection_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "sending_domain": { "type": "string", "minLength": 3, "maxLength": 255 }, "default_from_name": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "default_reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "is_active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Email Connections Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/email/connections/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### email.profiles.list Read GET /api/email/profiles through Nexus. Contract: GET /api/email/profiles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: email:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Email Profiles List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/email/profiles without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### email.profiles.create Invoke POST /api/email/profiles through Nexus. Contract: POST /api/email/profiles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: email:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "connection_id": "00000000-0000-4000-8000-000000000000", "profile_name": "example", "from_name": "example", "from_email": "user@example.com" } ``` Input schema: ```json { "type": "object", "properties": { "connection_id": { "type": "string", "minLength": 1 }, "profile_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_email": { "type": "string", "format": "email" }, "reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "app_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "is_default": { "type": "boolean" } }, "required": [ "connection_id", "profile_name", "from_name", "from_email" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Email Profiles Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/email/profiles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### email.profiles.update Invoke PATCH /api/email/profiles/{id} through Nexus. Contract: PATCH /api/email/profiles/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: email:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "profile_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_name": { "type": "string", "minLength": 1, "maxLength": 120 }, "from_email": { "type": "string", "format": "email" }, "reply_to_email": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "null" } ] }, "app_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "is_active": { "type": "boolean" }, "is_default": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Email Profiles Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/email/profiles/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### email.send Invoke POST /api/email/send through Nexus. Contract: POST /api/email/send Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: email:send Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "to": "user@example.com", "subject": "example" } ``` Input schema: ```json { "type": "object", "properties": { "profile_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "enum": [ "resend", "cloudflare_email" ] }, "from": { "$ref": "#/properties/profile_id" }, "to": { "anyOf": [ { "type": "string", "format": "email" }, { "type": "array", "items": { "type": "string", "format": "email" }, "minItems": 1 } ] }, "subject": { "type": "string", "minLength": 1, "maxLength": 998 }, "html": { "type": "string" }, "text": { "$ref": "#/properties/html" }, "reply_to": { "$ref": "#/properties/html" }, "cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "bcc": { "type": "array", "items": { "type": "string", "format": "email" } }, "tags": { "type": "array", "items": { "type": "object", "properties": { "name": { "$ref": "#/properties/profile_id" }, "value": { "$ref": "#/properties/profile_id" } }, "required": [ "name", "value" ], "additionalProperties": false } }, "message_stream": { "$ref": "#/properties/html" }, "app_id": { "$ref": "#/properties/html" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "filename": { "type": "string", "minLength": 1, "maxLength": 255 }, "content": { "$ref": "#/properties/profile_id" }, "content_type": { "type": "string", "minLength": 1, "maxLength": 255 } }, "required": [ "filename", "content" ], "additionalProperties": false }, "maxItems": 20 } }, "required": [ "to", "subject" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Email Send.", "additionalProperties": true } ``` Effects: May change state through POST /api/email/send. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### whatsapp.send Send a WhatsApp message via the org's connection through Nexus. Contract: POST /api/whatsapp/send Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: whatsapp:send Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "to": "example" } ``` Input schema: ```json { "type": "object", "properties": { "to": { "type": "string", "minLength": 5, "maxLength": 40 }, "connection_id": { "type": "string" }, "phone_number_id": { "$ref": "#/properties/connection_id" }, "app_id": { "$ref": "#/properties/connection_id" }, "type": { "type": "string", "enum": [ "text", "template" ] }, "text": { "type": "string", "minLength": 1, "maxLength": 4096 }, "preview_url": { "type": "boolean" }, "template": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 512 }, "language": { "type": "string", "minLength": 2, "maxLength": 20 }, "components": { "type": "array", "items": {} } }, "required": [ "name", "language" ], "additionalProperties": false } }, "required": [ "to" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Whatsapp Send.", "additionalProperties": true } ``` Effects: May change state through POST /api/whatsapp/send. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### payments.stripe.invoke Invoke POST /api/payments/stripe through Nexus. Contract: POST /api/payments/stripe Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: payments:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "operation": "checkout.sessions.create", "params": {} } ``` Input schema: ```json { "type": "object", "properties": { "operation": { "type": "string", "enum": [ "checkout.sessions.create", "checkout.sessions.retrieve", "checkout.sessions.expire", "prices.create", "products.create", "subscription_items.create", "subscription_items.update", "subscription_items.delete", "subscription_items.create_usage_record", "payment_intents.create", "payment_intents.retrieve", "payment_intents.cancel", "refunds.create", "billing_portal.sessions.create", "subscriptions.retrieve", "subscriptions.update", "invoices.create_preview", "subscriptions.create", "setup_intents.create", "customers.create", "customers.retrieve", "accounts.create", "accounts.retrieve", "accounts.update", "account_links.create", "login_links.create" ] }, "params": { "type": "object", "additionalProperties": {} } }, "required": [ "operation", "params" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Payments Stripe Invoke.", "additionalProperties": true } ``` Effects: May change state through POST /api/payments/stripe. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.overview.get Read GET /api/billing/overview through Nexus. Contract: GET /api/billing/overview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: billing:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Overview Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/billing/overview without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### billing.spend_caps.list Read GET /api/billing/spend-caps through Nexus. Contract: GET /api/billing/spend-caps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: billing:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Spend Caps List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/billing/spend-caps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### billing.spend_caps.upsert Invoke POST /api/billing/spend-caps through Nexus. Contract: POST /api/billing/spend-caps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: billing:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "scopeType": "organization", "monthlyCapCents": 1 } ``` Input schema: ```json { "type": "object", "properties": { "scopeType": { "type": "string", "enum": [ "organization", "user" ] }, "scopeValue": { "type": [ "string", "null" ] }, "monthlyCapCents": { "type": "number", "minimum": 0 }, "capMode": { "type": "string", "enum": [ "soft", "hard" ] }, "isActive": { "type": "boolean" }, "notifyThresholds": { "type": "array", "items": { "type": "number" } } }, "required": [ "scopeType", "monthlyCapCents" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Spend Caps Upsert.", "additionalProperties": true } ``` Effects: May change state through POST /api/billing/spend-caps. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.spend_caps.delete Invoke DELETE /api/billing/spend-caps/{id} through Nexus. Contract: DELETE /api/billing/spend-caps/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: billing:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Spend Caps Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/billing/spend-caps/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.byok_fee.update Invoke POST /api/billing/byok-fee through Nexus. Contract: POST /api/billing/byok-fee Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: billing:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "serviceFeeBps": 1 } ``` Input schema: ```json { "type": "object", "properties": { "serviceFeeBps": { "type": "number", "minimum": 0, "maximum": 10000 } }, "required": [ "serviceFeeBps" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Byok Fee Update.", "additionalProperties": true } ``` Effects: May change state through POST /api/billing/byok-fee. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.meters.list Read GET /api/billing/meters through Nexus. Contract: GET /api/billing/meters Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: billing:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Meters List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/billing/meters without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### billing.meter_settings.upsert Invoke POST /api/billing/meter-settings through Nexus. Contract: POST /api/billing/meter-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: billing:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "meterId": "example", "capMode": "soft" } ``` Input schema: ```json { "type": "object", "properties": { "meterId": { "type": "string", "minLength": 1 }, "capMode": { "type": "string", "enum": [ "soft", "hard", "hybrid" ] }, "hardCapUnits": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] }, "notifyThresholds": { "type": "array", "items": { "type": "number" } } }, "required": [ "meterId", "capMode" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Meter Settings Upsert.", "additionalProperties": true } ``` Effects: May change state through POST /api/billing/meter-settings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### turnstile.verify Invoke POST /platform/turnstile/verify through Nexus. Contract: POST /platform/turnstile/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: turnstile:verify Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "token": "example", "ip": "example", "appId": "example" } ``` Input schema: ```json { "type": "object", "properties": { "token": { "type": "string" }, "ip": { "type": [ "string", "null" ] }, "appId": { "type": [ "string", "null" ] } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Turnstile Verify.", "additionalProperties": true } ``` Effects: May change state through POST /platform/turnstile/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ratelimit.check Invoke POST /platform/ratelimit/check through Nexus. Contract: POST /platform/ratelimit/check Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ratelimit:check Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "key": "example", "limit": 1, "windowSeconds": 1 } ``` Input schema: ```json { "type": "object", "properties": { "key": { "type": "string", "minLength": 1, "maxLength": 200 }, "limit": { "type": "number", "minimum": 1, "maximum": 100000 }, "windowSeconds": { "type": "number", "minimum": 1, "maximum": 3600 }, "cost": { "type": "number", "minimum": 1, "maximum": 1000 }, "appId": { "type": [ "string", "null" ] } }, "required": [ "key", "limit", "windowSeconds" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Ratelimit Check.", "additionalProperties": true } ``` Effects: May change state through POST /platform/ratelimit/check. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.connections.list Invoke POST /platform/integrations/connections/list through Nexus. Contract: POST /platform/integrations/connections/list Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: integrations:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000", "app_resource_type": "example", "app_resource_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "app_resource_type": { "$ref": "#/properties/app_id" }, "app_resource_id": { "$ref": "#/properties/app_id" }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "include_inactive": { "type": "boolean", "default": false } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations Connections List.", "additionalProperties": true } ``` Effects: May change state through POST /platform/integrations/connections/list. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.connections.upsert Invoke POST /platform/integrations/connections/upsert through Nexus. Contract: POST /platform/integrations/connections/upsert Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: integrations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "connection_id": "2026-01-01" } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._:@+-]+$" }, "app_resource_type": { "type": "string", "minLength": 1, "default": "brand" }, "app_resource_id": { "$ref": "#/properties/app_id" }, "connected_by_user_id": { "type": [ "string", "null" ] }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "provider_user_id": { "$ref": "#/properties/app_id" }, "provider_username": { "type": [ "string", "null" ] }, "provider_display_name": { "type": [ "string", "null" ] }, "provider_avatar_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "provider_profile_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "access_token": { "type": [ "string", "null" ] }, "refresh_token": { "type": [ "string", "null" ] }, "credential_payload": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] }, "token_expires_at": { "type": [ "string", "null" ] }, "scope": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "disconnected", "deauthorized", "deleted", "error" ], "default": "active" }, "reactivate": { "type": "boolean", "default": false }, "metadata": { "$ref": "#/properties/credential_payload/anyOf/0", "default": {} }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "connection_id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations Connections Upsert.", "additionalProperties": true } ``` Effects: May change state through POST /platform/integrations/connections/upsert. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.connections.changes Poll the organization-scoped connection status change feed forward from a cursor, so an app learns about a disconnect before an action fails. Contract: POST /platform/integrations/connections/changes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: integrations:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000", "after_seq": 0, "limit": 100 } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "after_seq": { "type": "integer", "minimum": 0, "default": 0 }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations Connections Changes.", "additionalProperties": true } ``` Effects: May change state through POST /platform/integrations/connections/changes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.connections.disconnect Invoke POST /platform/integrations/connections/disconnect through Nexus. Contract: POST /platform/integrations/connections/disconnect Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: integrations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "connection_id": "2026-01-01" } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "connection_id": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[A-Za-z0-9._:@+-]+$" }, "mode": { "type": "string", "enum": [ "disconnect", "deauthorize", "delete" ], "default": "disconnect" }, "last_error": { "type": [ "string", "null" ] } }, "required": [ "connection_id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations Connections Disconnect.", "additionalProperties": true } ``` Effects: May change state through POST /platform/integrations/connections/disconnect. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.app_credentials.health Read GET /platform/integrations/app-credentials/health through Nexus. Contract: GET /platform/integrations/app-credentials/health Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: integrations:admin Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations App Credentials Health.", "additionalProperties": true } ``` Effects: Reads state through GET /platform/integrations/app-credentials/health without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### integrations.app_credentials.list Invoke POST /platform/integrations/app-credentials/list through Nexus. Contract: POST /platform/integrations/app-credentials/list Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: integrations:admin Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "environment": { "$ref": "#/properties/app_id" }, "include_inactive": { "type": "boolean", "default": false } }, "required": [ "app_id" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations App Credentials List.", "additionalProperties": true } ``` Effects: May change state through POST /platform/integrations/app-credentials/list. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### integrations.app_credentials.upsert Invoke POST /platform/integrations/app-credentials/upsert through Nexus. Contract: POST /platform/integrations/app-credentials/upsert Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: integrations:admin Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "app_id": "app_topolo_campaigns", "provider": "facebook", "client_id": "demo-client-id", "client_secret": "demo-client-secret" } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z0-9][a-z0-9_.:-]*$" }, "environment": { "type": "string", "minLength": 1, "default": "production" }, "credential_name": { "$ref": "#/properties/app_id" }, "client_id": { "$ref": "#/properties/app_id" }, "client_secret": { "$ref": "#/properties/app_id" }, "scopes": { "type": "array", "items": { "$ref": "#/properties/app_id" }, "default": [] }, "authorization_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "token_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "redirect_uri": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": {}, "default": {} }, "is_active": { "type": "boolean", "default": true } }, "required": [ "app_id", "provider", "client_id", "client_secret" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Integrations App Credentials Upsert.", "additionalProperties": true } ``` Effects: May change state through POST /platform/integrations/app-credentials/upsert. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### youtube.channel_profile.get Invoke POST /platform/youtube/channels/profile through Nexus. Contract: POST /platform/youtube/channels/profile Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: youtube:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "access_token": "example" } ``` Input schema: ```json { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1 }, "app_id": { "$ref": "#/properties/access_token" } }, "required": [ "access_token" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Youtube Channel Profile Get.", "additionalProperties": true } ``` Effects: May change state through POST /platform/youtube/channels/profile. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### youtube.videos.publish Invoke POST /platform/youtube/videos/upload through Nexus. Contract: POST /platform/youtube/videos/upload Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: youtube:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "access_token": "example", "video_url": "https://example.com", "title": "example" } ``` Input schema: ```json { "type": "object", "properties": { "access_token": { "type": "string", "minLength": 1 }, "video_url": { "type": "string", "format": "uri" }, "title": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 5000 }, "privacy_status": { "type": "string", "enum": [ "private", "unlisted", "public" ], "default": "private" }, "app_id": { "$ref": "#/properties/access_token" }, "brand_id": { "$ref": "#/properties/app_id" }, "post_id": { "$ref": "#/properties/app_id" } }, "required": [ "access_token", "video_url", "title" ], "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Youtube Videos Publish.", "additionalProperties": true } ``` Effects: May change state through POST /platform/youtube/videos/upload. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### platform_usage.events.create Invoke POST /platform/usage/events through Nexus. Contract: POST /platform/usage/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000", "appId": "example", "meter_key": "example" } ``` Input schema: ```json { "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "appId": { "$ref": "#/properties/app_id" }, "meter_key": { "type": "string", "minLength": 1, "maxLength": 80 }, "meterKey": { "type": "string", "minLength": 1, "maxLength": 80 }, "event_name": { "type": "string", "minLength": 1, "maxLength": 160 }, "eventName": { "type": "string", "minLength": 1, "maxLength": 160 }, "units": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000000, "default": 1 }, "user_id": { "type": [ "string", "null" ] }, "userId": { "type": [ "string", "null" ] }, "request_id": { "type": [ "string", "null" ] }, "requestId": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "additionalProperties": {} } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Platform Usage Events Create.", "additionalProperties": true } ``` Effects: May change state through POST /platform/usage/events. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### platform_usage.turnstile.get Read GET /platform/usage/turnstile through Nexus. Contract: GET /platform/usage/turnstile Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "start": "example", "end": "example" } ``` Input schema: ```json { "type": "object", "properties": { "orgId": { "type": "string" }, "start": { "$ref": "#/properties/orgId" }, "end": { "$ref": "#/properties/orgId" }, "appId": { "$ref": "#/properties/orgId" } }, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Platform Usage Turnstile Get.", "additionalProperties": true } ``` Effects: Reads state through GET /platform/usage/turnstile without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### platform_usage.meter_settings.backfill Invoke POST /platform/usage/meter-settings/backfill through Nexus. Contract: POST /platform/usage/meter-settings/backfill Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: usage:admin Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json {} ``` Input schema: ```json { "type": "object", "properties": {}, "additionalProperties": false, "$schema": "http://json-schema.org/draft-07/schema#" } ``` Output schema: ```json { "type": "object", "description": "Response returned by Platform Usage Meter Settings Backfill.", "additionalProperties": true } ``` Effects: May change state through POST /platform/usage/meter-settings/backfill. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo Pay source contract Human reference: https://docs.topolo.app/systems/topolo-pay Machine reference: https://docs.topolo.app/machine/systems/topolo-pay.json Source revisions: apps/TopoloPay@f7f8d29b3072c92900c77c0b64022b013d1e02f8 Deploy targets: 2; implemented actions: 58; declared actions: 58; uncatalogued served routes: 1; mobile contracts: 1; route signals: 41. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.get Get Pay analytics. Contract: GET /api/admin/analytics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "dateFrom": "example", "dateTo": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get Pay analytics.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/analytics without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### transactions.list List Pay transactions. Contract: GET /api/admin/transactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List transactions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/transactions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### customers.list List Pay customers. Contract: GET /api/admin/customers Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: customers:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List customers.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/customers without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### merchants.list Call GET /api/merchants. Contract: GET /api/merchants Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Merchants List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/merchants without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### subscriptions.checkout Create a subscription checkout session. Contract: POST /api/subscriptions/checkout Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "priceId": "example", "quantity": 1, "customerEmail": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "priceId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "customerEmail": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "minLength": 1 }, "externalSystem": { "type": "string", "minLength": 1 }, "externalUserId": { "type": "string", "minLength": 1 }, "externalOrgId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "successUrl": { "type": "string", "minLength": 1 }, "cancelUrl": { "type": "string", "minLength": 1 }, "trialPeriodDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "allowPromotionCodes": { "type": "boolean" }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "inlinePrice": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ] } }, "required": [ "productName", "unitAmount", "currency", "interval" ], "additionalProperties": false } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create subscription checkout.", "additionalProperties": true } ``` Effects: May change state through POST /api/subscriptions/checkout. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### pricing_plans.list List platform pricing plans. Contract: GET /api/pricing-plans Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example", "developerOrgId": "example", "includeInactive": "true" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "developerOrgId": { "type": "string", "minLength": 1 }, "includeInactive": { "type": "string", "enum": [ "true", "false" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List pricing plans.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pricing-plans without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### p2p.settlements.create Create a TopoloPay P2P settlement. Contract: POST /api/p2p/settlements Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "batch_id": "00000000-0000-4000-8000-000000000000", "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD", "total_minor": 1, "trigger": "threshold", "line_items": [ { "entry_id": "00000000-0000-4000-8000-000000000000", "request_id": "00000000-0000-4000-8000-000000000000", "capability_id": "00000000-0000-4000-8000-000000000000", "pricing_component": "example", "amount_minor": 1, "audit_correlation_id": "00000000-0000-4000-8000-000000000000" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "batch_id": { "type": "string", "minLength": 1 }, "buyer_org_id": { "type": "string", "minLength": 1 }, "seller_org_id": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "total_minor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "trigger": { "type": "string", "enum": [ "threshold", "schedule", "manual", "invoice", "delivery" ] }, "line_items": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "entry_id": { "type": "string", "minLength": 1 }, "request_id": { "type": "string", "minLength": 1 }, "capability_id": { "type": "string", "minLength": 1 }, "pricing_component": { "type": "string", "minLength": 1 }, "amount_minor": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "audit_correlation_id": { "type": "string", "minLength": 1 } }, "required": [ "entry_id", "request_id", "capability_id", "pricing_component", "amount_minor", "audit_correlation_id" ], "additionalProperties": false } } }, "required": [ "batch_id", "buyer_org_id", "seller_org_id", "currency", "total_minor", "trigger", "line_items" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create P2P settlement.", "additionalProperties": true } ``` Effects: May change state through POST /api/p2p/settlements. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### p2p.settlements.complete Persist a completed TopoloPay P2P settlement and publish its notification transition. Contract: POST /api/p2p/settlements/{batchId}/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "batchId": "example", "provider_status": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "batchId": { "type": "string", "minLength": 1 }, "provider_status": { "type": "string", "minLength": 1 } }, "required": [ "batchId", "provider_status" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete P2P settlement.", "additionalProperties": true } ``` Effects: May change state through POST /api/p2p/settlements/{batchId}/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### crypto_payments.create Create a TopoloPay crypto payment. Contract: POST /pay/crypto Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orderId": "example", "amountCents": 1, "currency": "USD", "merchantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1 }, "amountCents": { "type": "number", "exclusiveMinimum": 0 }, "currency": { "type": "string", "minLength": 1 }, "merchantId": { "type": "string", "minLength": 1 }, "customerEmail": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "redirectUrl": { "type": "string", "minLength": 1 }, "cancelUrl": { "type": "string", "minLength": 1 } }, "required": [ "orderId", "amountCents", "currency", "merchantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create crypto payment.", "additionalProperties": true } ``` Effects: May change state through POST /pay/crypto. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### crypto_payments.status.get Get TopoloPay crypto payment status. Contract: GET /pay/crypto/{chargeId}/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "chargeId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "chargeId": { "type": "string", "minLength": 1 } }, "required": [ "chargeId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get crypto payment status.", "additionalProperties": true } ``` Effects: Reads state through GET /pay/crypto/{chargeId}/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### merchants.fees.get Get TopoloPay merchant fees. Contract: GET /api/merchants/{merchantId}/fees Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "merchantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get merchant fees.", "additionalProperties": true } ``` Effects: Reads state through GET /api/merchants/{merchantId}/fees without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### subscriptions.payment_intent.create Create a subscription payment intent. Contract: POST /api/subscriptions/payment-intent Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "priceId": "example", "quantity": 1, "customerEmail": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "priceId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "customerEmail": { "type": "string", "minLength": 1 }, "customerName": { "type": "string", "minLength": 1 }, "externalSystem": { "type": "string", "minLength": 1 }, "externalUserId": { "type": "string", "minLength": 1 }, "externalOrgId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "trialPeriodDays": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "inlinePrice": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "interval": { "type": "string", "enum": [ "day", "week", "month", "year" ] } }, "required": [ "productName", "unitAmount", "currency", "interval" ], "additionalProperties": false } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create subscription payment intent.", "additionalProperties": true } ``` Effects: May change state through POST /api/subscriptions/payment-intent. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### subscriptions.by_external.get Get a subscription by external user id. Contract: GET /api/subscriptions/by-external/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example", "system": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 }, "includeAll": { "type": "string", "enum": [ "true", "false" ] } }, "required": [ "userId", "system" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get subscription by external user.", "additionalProperties": true } ``` Effects: Reads state through GET /api/subscriptions/by-external/{userId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### subscriptions.by_checkout_session.get Get a subscription by checkout session. Contract: GET /api/subscriptions/by-checkout-session/{sessionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get subscription by checkout session.", "additionalProperties": true } ``` Effects: Reads state through GET /api/subscriptions/by-checkout-session/{sessionId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### subscriptions.bind_external Bind external subscription metadata. Contract: POST /api/subscriptions/{id}/bind-external Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "externalSystem": { "type": "string", "minLength": 1 }, "externalOrgId": { "type": "string", "minLength": 1 }, "externalUserId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bind external subscription.", "additionalProperties": true } ``` Effects: May change state through POST /api/subscriptions/{id}/bind-external. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### subscriptions.get Get a TopoloPay subscription. Contract: GET /api/subscriptions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get subscription.", "additionalProperties": true } ``` Effects: Reads state through GET /api/subscriptions/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pricing_plans.create Create a TopoloPay pricing plan. Contract: POST /api/pricing-plans Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "displayName": "example", "pricingModel": "free" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "appId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "developerOrgId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1 }, "pricingModel": { "type": "string", "enum": [ "free", "included", "flat", "per_seat", "per_seat_tiered", "metered", "metered_tiered", "flat_plus_metered", "one_time", "sales_led" ] }, "unitLabel": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "billingCurrency": { "type": "string", "minLength": 1 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "day", "week", "month", "year" ] }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "revShareBps": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "pricingDetails": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tiers": { "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo" ], "additionalProperties": false } }, "tiersMode": { "type": "string", "enum": [ "graduated", "volume" ] }, "meteredUnitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatBaseAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "id", "displayName", "pricingModel" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create pricing plan.", "additionalProperties": true } ``` Effects: May change state through POST /api/pricing-plans. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### pricing_plans.bulk_create Bulk create TopoloPay pricing plans. Contract: POST /api/pricing-plans/bulk-register Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "plans": [ {} ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "plans": { "minItems": 1, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "required": [ "plans" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk create pricing plans.", "additionalProperties": true } ``` Effects: May change state through POST /api/pricing-plans/bulk-register. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### pricing_plans.by_app.list List TopoloPay pricing plans by app. Contract: GET /api/pricing-plans/by-app/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List pricing by app.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pricing-plans/by-app/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pricing_plans.get Get a TopoloPay pricing plan. Contract: GET /api/pricing-plans/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get pricing plan.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pricing-plans/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### platform_pricing.get Get Topolo platform pricing. Contract: GET /api/platform-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get platform pricing.", "additionalProperties": true } ``` Effects: Reads state through GET /api/platform-pricing without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### platform_pricing.update Update Topolo platform pricing. Contract: PUT /api/platform-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "base": { "planId": "example", "monthlyCentsPerSeat": 1 }, "includedFreeInBase": [ { "appId": "example", "headline": "example" } ], "platformCapabilities": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "base": { "type": "object", "properties": { "planId": { "type": "string", "minLength": 1 }, "monthlyCentsPerSeat": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "minimumSeats": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "seatTiers": { "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo", "unitAmountCents" ], "additionalProperties": false } } }, "required": [ "planId", "monthlyCentsPerSeat" ], "additionalProperties": false }, "includedFreeInBase": { "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "headline": { "type": "string", "minLength": 1 }, "marketingPath": { "type": "string", "minLength": 1 } }, "required": [ "appId", "headline" ], "additionalProperties": false } }, "platformCapabilities": { "type": "array", "items": { "type": "string" } }, "platformTagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schemaVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "editorUserId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update platform pricing.", "additionalProperties": true } ``` Effects: May change state through PUT /api/platform-pricing. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### subscription_items.list List subscription items. Contract: GET /api/subscriptions/{subId}/items Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "subId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 } }, "required": [ "subId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List subscription items.", "additionalProperties": true } ``` Effects: Reads state through GET /api/subscriptions/{subId}/items without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### subscription_items.create Create a subscription item. Contract: POST /api/subscriptions/{subId}/items Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "subId": "example", "pricingPlanId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 }, "pricingPlanId": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "minimum": 0 }, "itemKind": { "type": "string", "enum": [ "base", "app" ] } }, "required": [ "subId", "pricingPlanId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create subscription item.", "additionalProperties": true } ``` Effects: May change state through POST /api/subscriptions/{subId}/items. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### subscription_items.update Update a subscription item. Contract: PATCH /api/subscriptions/{subId}/items/{itemId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "subId": "example", "itemId": "example", "quantity": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 }, "itemId": { "type": "string", "minLength": 1 }, "quantity": { "type": "number", "minimum": 0 } }, "required": [ "subId", "itemId", "quantity" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update subscription item.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/subscriptions/{subId}/items/{itemId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### subscription_items.delete Delete a subscription item. Contract: DELETE /api/subscriptions/{subId}/items/{itemId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "subId": "example", "itemId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subId": { "type": "string", "minLength": 1 }, "itemId": { "type": "string", "minLength": 1 } }, "required": [ "subId", "itemId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete subscription item.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/subscriptions/{subId}/items/{itemId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_subscription_items.list List organization subscription items. Contract: GET /api/subscriptions/by-external-org/{orgId}/items Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "system": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "system" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization subscription items.", "additionalProperties": true } ``` Effects: Reads state through GET /api/subscriptions/by-external-org/{orgId}/items without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_subscriptions.summary.get Get organization subscription summary. Contract: GET /api/subscriptions/by-external-org/{orgId}/summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization subscription summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/subscriptions/by-external-org/{orgId}/summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_subscriptions.base_seat_count.update Update organization subscription base seat count. Contract: POST /api/subscriptions/by-external-org/{orgId}/base-seat-count Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "system": "example", "seatCount": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "system": { "type": "string", "minLength": 1 }, "seatCount": { "type": "number", "minimum": 0 } }, "required": [ "orgId", "system", "seatCount" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update base seat count.", "additionalProperties": true } ``` Effects: May change state through POST /api/subscriptions/by-external-org/{orgId}/base-seat-count. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### connect.onboard Start TopoloPay Connect onboarding. Contract: POST /admin/connect/onboard Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: merchants:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "merchantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 }, "returnUrl": { "type": "string", "minLength": 1 }, "refreshUrl": { "type": "string", "minLength": 1 }, "email": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Start Connect onboarding.", "additionalProperties": true } ``` Effects: May change state through POST /admin/connect/onboard. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### connect.status.get Get TopoloPay Connect status. Contract: GET /admin/connect/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: merchants:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "merchantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get Connect status.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/connect/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### connect.dashboard_link.create Create a TopoloPay Connect dashboard link. Contract: POST /admin/connect/dashboard-link Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: merchants:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "merchantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create Connect dashboard link.", "additionalProperties": true } ``` Effects: May change state through POST /admin/connect/dashboard-link. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.transactions.results.list List TopoloPay transaction search results. Contract: GET /admin/transactions/results Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List transaction results.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/transactions/results without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.transactions.search Search TopoloPay transactions. Contract: GET /admin/transactions/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Search transactions.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/transactions/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.customers.search Search TopoloPay customers. Contract: GET /admin/customers/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: customers:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "customerSearch": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "customerSearch": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Search customers.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/customers/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.customers.history.get Get TopoloPay customer history. Contract: GET /api/admin/customers/{email}/history Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: customers:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "email": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "minLength": 1 } }, "required": [ "email" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get customer history.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/customers/{email}/history without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.audit.list List TopoloPay audit logs. Contract: GET /api/admin/audit Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "action": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "action": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List audit logs.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/audit without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.export.transactions Export TopoloPay transactions. Contract: GET /api/admin/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "format": "csv", "type": "transactions", "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "format": { "type": "string", "enum": [ "csv" ] }, "type": { "type": "string", "enum": [ "transactions", "reconciliation", "summary" ] }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Export transactions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### orders.create Call POST /order. Contract: POST /order Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orderId": "example", "amount": 1, "currency": "USD", "merchantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orderId": { "type": "string", "minLength": 1 }, "amount": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "currency": { "type": "string", "minLength": 1 }, "merchantId": { "type": "string", "minLength": 1 }, "venueId": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "customer": { "type": "object", "properties": { "email": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "customerEmail": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "receipt_email": { "type": "string", "minLength": 1 }, "statement_descriptor": { "type": "string", "minLength": 1 } }, "required": [ "orderId", "amount", "currency", "merchantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Orders Create.", "additionalProperties": true } ``` Effects: May change state through POST /order. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### orders.cancel Call POST /order/{paymentId}/cancel. Contract: POST /order/{paymentId}/cancel Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "paymentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "paymentId": { "type": "string", "minLength": 1 } }, "required": [ "paymentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Orders Cancel.", "additionalProperties": true } ``` Effects: May change state through POST /order/{paymentId}/cancel. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### payment.status.get Call GET /payment/{sessionId}/status. Contract: GET /payment/{sessionId}/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Payment Status Get.", "additionalProperties": true } ``` Effects: Reads state through GET /payment/{sessionId}/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.transactions.page.list Call GET /admin/transactions. Contract: GET /admin/transactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 10000 }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Transactions Page List.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/transactions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.customers.page.list Call GET /admin/customers. Contract: GET /admin/customers Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: customers:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Customers Page List.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/customers without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.customers.list Call GET /admin/customers/list. Contract: GET /admin/customers/list Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: customers:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Customers List.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/customers/list without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.audit.page.get Call GET /admin/audit. Contract: GET /admin/audit Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Audit Page Get.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/audit without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.audit.logs.list Call GET /admin/audit/logs. Contract: GET /admin/audit/logs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "auditAction": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "auditAction": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Audit Logs List.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/audit/logs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.export.transactions_page Call GET /admin/export/transactions. Contract: GET /admin/export/transactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "format": "csv", "type": "transactions", "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "format": { "type": "string", "enum": [ "csv" ] }, "type": { "type": "string", "enum": [ "transactions", "reconciliation", "summary" ] }, "search": { "type": "string", "minLength": 1 }, "merchant": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "method": { "type": "string", "minLength": 1 }, "dateFrom": { "type": "string", "minLength": 1 }, "dateTo": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Export Transactions Page.", "additionalProperties": true } ``` Effects: Reads state through GET /admin/export/transactions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.transaction.get Call GET /api/admin/transaction/{id}. Contract: GET /api/admin/transaction/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Transaction Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/transaction/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.refund.create Call POST /api/admin/refund/{id}. Contract: POST /api/admin/refund/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:refund Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "amount": 1, "reason": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "amount": { "type": "number", "exclusiveMinimum": 0 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "id", "amount", "reason" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Refund Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/refund/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.invoices.list List Stripe invoices visible to the current organization or platform operator. Contract: GET /api/admin/invoices Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: invoices:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "starting_after": "example", "status": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "starting_after": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/invoices without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.invoices.link.get Get the hosted link for an accessible invoice. Contract: GET /api/admin/invoices/{invoiceId}/link Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: invoices:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "invoiceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invoiceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "invoiceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/invoices/{invoiceId}/link without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.merchants.list List merchant accounts visible to the current workspace. Contract: GET /api/admin/merchants Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: merchants:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/merchants without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.merchants.get Get a merchant account visible to the current workspace. Contract: GET /api/admin/merchants/{merchantId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: merchants:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "merchantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "merchantId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "merchantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/merchants/{merchantId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.delete Delete a non-default empty Pay workspace. Contract: DELETE /api/pay/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/pay/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.data.export Export the caller organization's billing, payment, settlement, usage, analytics, and attributed audit records across Pay's split stores. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase organization-authored Pay content while retaining immutable financial and provider reconciliation records. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "example", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.data_protection.canary Check whether retained merchant, customer, transaction, refund, and provider payload fields are encrypted for an organization. Contract: GET /api/organizations/{organizationId}/data-protection Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data-protection without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## Topolo Platform source contract Human reference: https://docs.topolo.app/systems/topolo-platform Machine reference: https://docs.topolo.app/machine/systems/topolo-platform.json Source revisions: topolo-platform/core/TopoloAuth@515376de81efed9734741b2a1d691c8195243073, topolo-platform/core/TopoloCloudControl@515376de81efed9734741b2a1d691c8195243073, system-apps/TopoloDocs@content-sha256:f1156f3f8bfa67eea5ea769c2e21502bf7883b145bf30212f0ea11cc6a2b1140, topolo-platform/services/TopoloLocalize@515376de81efed9734741b2a1d691c8195243073, topolo-platform/packages/topolo-ui-kit@515376de81efed9734741b2a1d691c8195243073 Deploy targets: 5; implemented actions: 232; declared actions: 232; uncatalogued served routes: 4; mobile contracts: 1; route signals: 147. ### organizations.list Read organizations visible to the authenticated Auth principal. Contract: GET /api/organizations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "includeDeleted": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "includeDeleted": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organizations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.get Read organization details by organization id. Contract: GET /api/organizations/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "includeDeleted": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.export Export the portable Auth-owned organization, membership, access, preference, session, and audit record set. Contract: GET /api/organizations/{orgId}/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Export organization identity data.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.billable_seats.get Read the billable seat summary for one organization. Contract: GET /api/organizations/{orgId}/billable-seat-summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization billable seats.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/billable-seat-summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.create Create an organization and optionally invite its first owner. Contract: POST /api/organizations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "ownerEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "ownerName": { "type": "string", "minLength": 1 } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.update Update one organization. Contract: PATCH /api/organizations/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "slug": { "type": "string", "minLength": 1 }, "logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "status": { "type": "string", "enum": [ "active", "inactive", "suspended", "deleted" ] }, "isActive": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/organizations/{orgId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.delete Soft-delete one organization and revoke its active sessions. Contract: DELETE /api/organizations/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete organization.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.delete_permanently Permanently purge Auth-owned data for one soft-deleted organization. Contract: DELETE /api/organizations/{orgId}/permanent Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Permanently delete organization identity data.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/permanent. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.restore Restore one soft-deleted organization. Contract: POST /api/organizations/{orgId}/restore Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Restore organization.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/restore. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.owner_invite.resend Issue a fresh owner invitation for one organization. Contract: POST /api/organizations/{orgId}/resend-owner-invite Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Resend organization owner invite.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/resend-owner-invite. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_principals.list List human and headless principals assignable in one organization. Contract: GET /api/organizations/{orgId}/principals Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization principals.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/principals without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_principals.create Create a headless agent principal accountable to a human organization member. Contract: POST /api/organizations/{orgId}/principals Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "principalType": "agent_employee", "displayName": "example", "accountableUserId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalType": { "type": "string", "const": "agent_employee" }, "displayName": { "type": "string", "minLength": 1 }, "accountableUserId": { "type": "string", "minLength": 1 }, "serviceGrants": { "maxItems": 500, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^[^:]+:.+$" }, { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "scopes": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "appId", "scopes" ], "additionalProperties": false } ] } }, "externalSubjectType": { "type": "string", "minLength": 1 }, "externalSubjectId": { "type": "string", "minLength": 1 }, "templateName": { "type": "string", "minLength": 1 }, "policyRef": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "principalType", "displayName", "accountableUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization principal.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/principals. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_principals.update Update a headless organization principal and its service grants. Contract: PATCH /api/organizations/{orgId}/principals/{principalId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "principalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "suspended", "deleted" ] }, "accountableUserId": { "type": "string", "minLength": 1 }, "serviceGrants": { "maxItems": 500, "type": "array", "items": { "anyOf": [ { "type": "string", "pattern": "^[^:]+:.+$" }, { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "scopes": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "appId", "scopes" ], "additionalProperties": false } ] } }, "policyRef": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "orgId", "principalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization principal.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/organizations/{orgId}/principals/{principalId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### principal_credentials.list List credentials issued to one headless principal. Contract: GET /api/organizations/{orgId}/principals/{principalId}/credentials Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "principalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "principalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List principal credentials.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/principals/{principalId}/credentials without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### principal_credentials.issue Issue a new client credential to one active headless principal. Contract: POST /api/organizations/{orgId}/principals/{principalId}/credentials Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "principalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "orgId", "principalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Issue principal credential.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/principals/{principalId}/credentials. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### principal_credentials.revoke Revoke one headless principal credential. Contract: DELETE /api/organizations/{orgId}/principals/{principalId}/credentials/{credentialId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "principalId": "example", "credentialId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "principalId": { "type": "string", "minLength": 1 }, "credentialId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "principalId", "credentialId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke principal credential.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/principals/{principalId}/credentials/{credentialId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_member_roles.assign Assign an additional organization or application role to a member. Contract: POST /api/organizations/{orgId}/members/{userId}/roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "userId": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "userId", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assign organization member role.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/members/{userId}/roles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_member_roles.revoke Revoke an additional organization or application role from a member. Contract: DELETE /api/organizations/{orgId}/members/{userId}/roles/{roleKey} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "userId": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "userId", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke organization member role.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/members/{userId}/roles/{roleKey}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_billing.preview Preview billing for a proposed organization seat quantity. Contract: POST /api/organizations/{orgId}/billing-preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "targetSeatQuantity": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preview organization billing.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/billing-preview. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_billing.portal.create Create a billing portal session for one organization. Contract: POST /api/organizations/{orgId}/billing-portal Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "returnUrl": { "type": "string", "format": "uri" } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization billing portal session.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/billing-portal. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_onboarding.complete Mark organization-wide onboarding complete for one installed service. Contract: POST /api/organizations/{orgId}/services/{appId}/onboarding-complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete organization service onboarding.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/onboarding-complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### my_service_onboarding.get Read the caller's onboarding progress for one installed service. Contract: GET /api/organizations/{orgId}/services/{appId}/onboarding/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my service onboarding progress.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/onboarding/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_service_onboarding.update Replace the caller's onboarding progress for one installed service. Contract: PUT /api/organizations/{orgId}/services/{appId}/onboarding/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "progress": { "currentStepId": "example", "completedStepIds": [ "example" ], "dismissedStepIds": [ "example" ] } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "progress": { "type": "object", "properties": { "currentStepId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "completedStepIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "dismissedStepIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "dismissedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "required": [ "orgId", "appId", "progress" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update my service onboarding progress.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/services/{appId}/onboarding/me. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### my_service_tours.list List the caller's tour progress for one installed service. Contract: GET /api/organizations/{orgId}/services/{appId}/tours/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my service tour progress.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/tours/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_service_tours.update Replace the caller's progress for one service tour. Contract: PUT /api/organizations/{orgId}/services/{appId}/tours/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "tourId": "example", "progress": { "currentStep": 1, "completed": true, "skipped": true } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "tourId": { "type": "string", "minLength": 1 }, "progress": { "type": "object", "properties": { "currentStep": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "completed": { "type": "boolean" }, "skipped": { "type": "boolean" }, "completedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } }, "required": [ "orgId", "appId", "tourId", "progress" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update my service tour progress.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/services/{appId}/tours/me. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### households.list List households available to the caller. Contract: GET /api/households Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my households.", "additionalProperties": true } ``` Effects: Reads state through GET /api/households without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### households.create Create a household owned by the caller. Contract: POST /api/households Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create household.", "additionalProperties": true } ``` Effects: May change state through POST /api/households. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### households.get Read one household available to the caller. Contract: GET /api/households/{householdId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get household.", "additionalProperties": true } ``` Effects: Reads state through GET /api/households/{householdId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### households.update Update one household managed by the caller. Contract: PUT /api/households/{householdId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update household.", "additionalProperties": true } ``` Effects: May change state through PUT /api/households/{householdId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### households.delete Delete one household managed by the caller. Contract: DELETE /api/households/{householdId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete household.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/households/{householdId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_members.add Add an existing or invited user to a household. Contract: POST /api/households/{householdId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add household member.", "additionalProperties": true } ``` Effects: May change state through POST /api/households/{householdId}/members. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_members.remove Remove one user from a household. Contract: DELETE /api/households/{householdId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "householdId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "householdId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove household member.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/households/{householdId}/members. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_dependents.add Attach an existing or new dependent to a household. Contract: POST /api/households/{householdId}/dependents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "householdId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "dependentId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "birthdate": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "relationshipRole": { "type": "string", "minLength": 1 } }, "required": [ "householdId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add household dependent.", "additionalProperties": true } ``` Effects: May change state through POST /api/households/{householdId}/dependents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### household_dependents.remove Remove one dependent from a household. Contract: DELETE /api/households/{householdId}/dependents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "householdId": "example", "dependentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "householdId": { "type": "string", "minLength": 1 }, "dependentId": { "type": "string", "minLength": 1 } }, "required": [ "householdId", "dependentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove household dependent.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/households/{householdId}/dependents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.list List bounded organization-to-application access relationships across the platform. Contract: GET /api/organization-services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization service relationships.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization-services without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_service_relationships.get Read one organization-to-application access relationship. Contract: GET /api/organization-services/{relationshipId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "relationshipId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "relationshipId": { "type": "string", "minLength": 1 } }, "required": [ "relationshipId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization service relationship.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization-services/{relationshipId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_service_relationships.create Grant an organization access to one application. Contract: POST /api/organization-services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "accessLevel": { "type": "string", "enum": [ "basic", "premium", "enterprise", "custom" ] }, "enabled": { "type": "boolean" }, "settings": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "expiresAt": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1 } ] }, { "type": "null" } ] } }, "required": [ "organizationId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization service relationship.", "additionalProperties": true } ``` Effects: May change state through POST /api/organization-services. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.update Update one organization-to-application access relationship. Contract: PUT /api/organization-services/{relationshipId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "relationshipId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "relationshipId": { "type": "string", "minLength": 1 }, "accessLevel": { "type": "string", "enum": [ "basic", "premium", "enterprise", "custom" ] }, "enabled": { "type": "boolean" }, "settings": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "expiresAt": { "anyOf": [ { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "string", "minLength": 1 } ] }, { "type": "null" } ] }, "status": { "type": "string", "enum": [ "active", "suspended", "expired" ] } }, "required": [ "relationshipId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization service relationship.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organization-services/{relationshipId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.delete Revoke an organization application relationship. Contract: DELETE /api/organization-services/{relationshipId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "relationshipId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "relationshipId": { "type": "string", "minLength": 1 } }, "required": [ "relationshipId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete organization service relationship.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organization-services/{relationshipId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_service_relationships.check Check one exact organization and application relationship without enumerating the catalog. Contract: GET /api/organization-services/check/{organizationId}/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Check organization service access.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organization-services/check/{organizationId}/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_organizations.list List a bounded page of organizations with access to one application. Contract: GET /api/services/{appId}/organizations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service organizations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/organizations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### invitations.list List a bounded page of organization invitations. Contract: GET /api/invitations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example", "page": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List invitations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/invitations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### invitations.create Create an organization invitation and optionally notify its recipient. Contract: POST /api/invitations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example", "email": "user@example.com", "role": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "role": { "type": "string", "minLength": 1 }, "expiresInDays": { "type": "integer", "exclusiveMinimum": 0, "maximum": 3650 }, "maxUses": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create invitation.", "additionalProperties": true } ``` Effects: May change state through POST /api/invitations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### invitations.delete Delete one organization invitation. Contract: DELETE /api/invitations/{invitationId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "invitationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "invitationId": { "type": "string", "minLength": 1 } }, "required": [ "invitationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete invitation.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/invitations/{invitationId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### machine_registry.get Resolve machine launch metadata for one exact accessible application. Contract: GET /api/machine/registry Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 } }, "required": [ "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get machine launch metadata.", "additionalProperties": true } ``` Effects: Reads state through GET /api/machine/registry without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### machine_handoffs.create Create a short-lived handoff for one exact accessible application and launch intent. Contract: POST /api/machine/handoffs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "app_id": "00000000-0000-4000-8000-000000000000", "intent": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "app_id": { "type": "string", "minLength": 1 }, "intent": { "type": "string", "minLength": 1 }, "target": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "required": [ "app_id", "intent" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create machine handoff.", "additionalProperties": true } ``` Effects: May change state through POST /api/machine/handoffs. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### my_app_switcher_preferences.get Read the caller's bounded app switcher preferences. Contract: GET /api/app-switcher/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "preferences", "revision", "updatedAt" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Reads the authenticated caller only. Returns the current monotonic preference revision. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_app_switcher_preferences.events List caller-owned preference revisions after an observed revision and return current state. Contract: GET /api/app-switcher/preferences/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "afterRevision": 0, "limit": 50 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "afterRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mutationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "changedKeys": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "favorites", "hidden", "tileSize", "theme", "workspacePins", "widgetDisplay", "chatWidgetState" ] } } }, "required": [ "preferences", "revision", "updatedAt", "mutationId", "changedKeys" ], "additionalProperties": false } }, "state": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "preferences", "revision", "updatedAt" ], "additionalProperties": false } }, "required": [ "events", "state" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Reads the authenticated caller only. Does not consume or delete events. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_app_switcher_preferences.update Update the caller's bounded app switcher preferences. Contract: PUT /api/app-switcher/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "baseRevision": 0, "mutationId": "cli-example-1", "favorites": [ "app_topolo_one" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false }, "baseRevision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "mutationId": { "type": "string", "minLength": 1, "maxLength": 128 } }, "required": [ "baseRevision", "mutationId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "preferences": { "type": "object", "properties": { "favorites": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "hidden": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } }, "tileSize": { "type": "string", "enum": [ "icon", "compact", "comfortable", "large" ] }, "theme": { "type": "string", "enum": [ "light", "dark" ] }, "workspacePins": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "widgetDisplay": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "object", "properties": { "heroMetricKey": { "type": "string", "minLength": 1 }, "secondaryMetricKeys": { "maxItems": 4, "type": "array", "items": { "type": "string", "minLength": 1 } }, "launchPath": { "type": "string", "maxLength": 500, "pattern": "^\\/.*" } }, "additionalProperties": false } } }, "chatWidgetState": { "type": "object", "properties": { "version": { "type": "number", "const": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "launcherOpen": { "type": "boolean" }, "audienceFilter": { "type": "string", "enum": [ "all", "human", "agent", "channel" ] }, "statusFilter": { "type": "string", "enum": [ "all", "unread", "favorites" ] }, "openConversations": { "maxItems": 2, "type": "array", "items": { "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "contact": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "human", "agent", "channel" ] }, "id": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "subtitle": { "type": "string" }, "avatarUrl": { "type": "string", "format": "uri" }, "status": { "type": "string" }, "conversationId": { "type": "string", "minLength": 1 }, "unreadCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "isFavorite": { "type": "boolean" }, "favoriteKey": { "type": "string" }, "lastActivityAt": { "type": "string" }, "lastMessagePreview": { "type": "string" }, "muted": { "type": "boolean" }, "archived": { "type": "boolean" } }, "required": [ "type", "id", "displayName" ], "additionalProperties": false }, "draft": { "type": "string", "maxLength": 4000 }, "minimized": { "type": "boolean" } }, "required": [ "conversationId", "contact" ], "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "favorites", "hidden", "tileSize", "workspacePins", "widgetDisplay", "chatWidgetState" ], "additionalProperties": false }, "revision": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "updatedAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mutationId": { "type": "string", "minLength": 1, "maxLength": 128 }, "changedKeys": { "minItems": 1, "maxItems": 7, "type": "array", "items": { "type": "string", "enum": [ "favorites", "hidden", "tileSize", "theme", "workspacePins", "widgetDisplay", "chatWidgetState" ] } } }, "required": [ "preferences", "revision", "updatedAt", "mutationId", "changedKeys" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Merges only supplied preference fields. Creates one caller-owned revision event. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Retry an ambiguous request with the same mutationId.,On revision conflict, retain local dirty fields and retry against the returned revision. ### my_i18n_preferences.get Resolve the caller's language preferences. Contract: GET /api/i18n/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "00000000-0000-4000-8000-000000000000", "locale": "en-US", "lang": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "lang": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my language preferences.", "additionalProperties": true } ``` Effects: Reads state through GET /api/i18n/preferences without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### my_i18n_preferences.update Update the caller's language preference. Contract: PUT /api/i18n/preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "locale": "en-US", "language": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "locale": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update my language preferences.", "additionalProperties": true } ``` Effects: May change state through PUT /api/i18n/preferences. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_preferences.list List notification preferences for the caller or a platform-managed user. Contract: GET /api/users/{userId}/notification-preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "org_id": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user notification preferences.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/notification-preferences without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_preferences.replace Replace the bounded notification preference set for the caller or a platform-managed user. Contract: PUT /api/users/{userId}/notification-preferences Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "rows": [ { "event_type": "system.example", "channel": "email", "enabled": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "query": { "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "enabled": { "type": "boolean" } }, "required": [ "event_type", "channel", "enabled" ], "additionalProperties": false } } }, "required": [ "userId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace user notification preferences.", "additionalProperties": true } ``` Effects: May change state through PUT /api/users/{userId}/notification-preferences. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_preferences.resolve Resolve effective delivery channels and action policy for one user and event. Contract: GET /api/users/{userId}/notification-preferences/resolve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "user_demo", "org_id": "org_topolo_platform", "event_type": "campaigns.send_completed" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "org_id": { "type": "string", "minLength": 1 }, "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "source_app_id": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "surface": { "type": "string", "enum": [ "notification", "action" ] }, "category": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "priority": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "default_channel": { "anyOf": [ { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp" ] }, { "minItems": 1, "maxItems": 5, "type": "array", "items": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp" ] } } ] }, "transactional": { "type": "string", "enum": [ "true", "false" ] } }, "required": [ "userId", "org_id", "event_type" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Resolve user notification preferences.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/notification-preferences/resolve without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_channels.list List verified and pending notification addresses for one visible user. Contract: GET /api/users/{userId}/notification-channels Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user notification channels.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/notification-channels without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_channels.create Register a notification address for one visible user. Contract: POST /api/users/{userId}/notification-channels Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "channel": "email", "address": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "whatsapp" ] }, "address": { "type": "string", "minLength": 1 }, "label": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "userId", "channel", "address" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create user notification channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/notification-channels. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_channels.verify Mark one notification address as verified. Contract: POST /api/users/{userId}/notification-channels/{channelId}/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "channelId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Verify user notification channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/notification-channels/{channelId}/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_channels.delete Delete one notification address from a visible user. Contract: DELETE /api/users/{userId}/notification-channels/{channelId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "channelId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "channelId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "channelId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user notification channel.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/notification-channels/{channelId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_notification_policy.list List delivery rules enforced by one managed organization. Contract: GET /api/organizations/{orgId}/notification-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization notification policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/notification-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_notification_policy.replace Replace delivery rules enforced by one managed organization. Contract: PUT /api/organizations/{orgId}/notification-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "rows": [ { "event_type": "system.example", "channel": "email", "forbidden": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "forbidden": { "type": "boolean" } }, "required": [ "event_type", "channel", "forbidden" ], "additionalProperties": false } } }, "required": [ "orgId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace organization notification policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/notification-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_notification_action_policy.list List action-delivery policy rules for one managed organization. Contract: GET /api/organizations/{orgId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization notification action policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/notification-action-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_notification_action_policy.replace Replace action-delivery policy rules for one managed organization. Contract: PUT /api/organizations/{orgId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "rows": [ { "delivery_mode": "immediate", "required_action": true, "enabled": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "source_app_id": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "surface": { "type": "string", "enum": [ "notification", "action", "*" ] }, "category": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "priority": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "delivery_mode": { "type": "string", "enum": [ "immediate", "digest", "in_app_only", "muted" ] }, "required_action": { "type": "boolean" }, "quiet_hours": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "digest": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "escalation": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "enabled": { "type": "boolean" } }, "required": [ "delivery_mode", "required_action", "enabled" ], "additionalProperties": false } } }, "required": [ "orgId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace organization notification action policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/notification-action-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_notification_action_policy.list List action-delivery policy rules for the caller or a user in a managed organization. Contract: GET /api/organizations/{orgId}/users/{userId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user notification action policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/users/{userId}/notification-action-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_notification_action_policy.replace Replace action-delivery policy rules for the caller or a user in a managed organization. Contract: PUT /api/organizations/{orgId}/users/{userId}/notification-action-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "userId": "example", "rows": [ { "delivery_mode": "immediate", "required_action": true, "enabled": true } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "rows": { "maxItems": 500, "type": "array", "items": { "type": "object", "properties": { "source_app_id": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "event_type": { "type": "string", "pattern": "^(?:\\*|[a-z][a-z0-9_]*(?:\\.[a-z0-9_]+){1,3})$" }, "surface": { "type": "string", "enum": [ "notification", "action", "*" ] }, "category": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "priority": { "type": "string", "pattern": "^(?:\\*|[A-Za-z0-9][A-Za-z0-9_.:-]{0,127})$" }, "channel": { "type": "string", "enum": [ "email", "push", "sms", "in_app", "whatsapp", "*" ] }, "delivery_mode": { "type": "string", "enum": [ "immediate", "digest", "in_app_only", "muted" ] }, "required_action": { "type": "boolean" }, "quiet_hours": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "digest": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "escalation": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "enabled": { "type": "boolean" } }, "required": [ "delivery_mode", "required_action", "enabled" ], "additionalProperties": false } } }, "required": [ "orgId", "userId", "rows" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace user notification action policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/users/{userId}/notification-action-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_connected_apps.list List developer OAuth applications currently connected to the caller. Contract: GET /api/developer-oauth/connected-apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my connected OAuth apps.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-oauth/connected-apps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### developer_oauth_connected_apps.disconnect Revoke the caller's refresh tokens for one connected OAuth client. Contract: DELETE /api/developer-oauth/connected-apps/{clientId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "clientId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "clientId": { "type": "string", "minLength": 1 } }, "required": [ "clientId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Disconnect OAuth app.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-oauth/connected-apps/{clientId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_clients.list List OAuth clients owned by the caller's developer organization. Contract: GET /api/developer-oauth/clients Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List developer OAuth clients.", "additionalProperties": true } ``` Effects: Reads state through GET /api/developer-oauth/clients without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### developer_oauth_clients.create Create an OAuth client for the caller's developer organization and return its secret once when confidential. Contract: POST /api/developer-oauth/clients Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "developer_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "developer_id": { "type": "string", "minLength": 1 }, "developer_app_id": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] }, "client_type": { "type": "string", "enum": [ "public", "confidential" ] }, "grant_types": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "redirect_uris": { "maxItems": 100, "type": "array", "items": { "type": "string", "format": "uri" } }, "allowed_scopes": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "homepage_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] } }, "required": [ "name", "developer_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create developer OAuth client.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-oauth/clients. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_clients.rotate_secret Rotate and return the secret for one confidential OAuth client. Contract: POST /api/developer-oauth/clients/{id}/rotate-secret Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Rotate developer OAuth client secret.", "additionalProperties": true } ``` Effects: May change state through POST /api/developer-oauth/clients/{id}/rotate-secret. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### developer_oauth_clients.revoke Revoke one OAuth client and all of its active refresh tokens. Contract: DELETE /api/developer-oauth/clients/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke developer OAuth client.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/developer-oauth/clients/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_config.get Read merged login branding and active event config for one application. Contract: GET /api/login-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get application login config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-config/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### login_config.update Update only the supplied login config fields for one application. Contract: PUT /api/login-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "logo_dark_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "features": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "allowed_providers": { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, "authenticated_home_path": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "magic_link_delivery_mode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_avatar_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "enable_cursor_effects": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "enable_mini_games": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "mini_game_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_css": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "custom_head_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "copyright_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update application login config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/login-config/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### master_login_config.get Read the platform-wide default login branding config. Contract: GET /api/login-config-master Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get master login config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-config-master without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### master_login_config.update Update only the supplied platform-wide default login fields. Contract: PUT /api/login-config-master Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "brand_name": "example", "brand_tagline": "example", "brand_logo_url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "brand_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand_tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "brand_logo_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "brand_logo_dark_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "default_layout": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "enable_cursor_effects": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "enable_mini_games": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "mini_game_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "show_social_links": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "social_links": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update master login config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/login-config-master. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### landing_config.get Read the app-specific landing presentation, returning-user login action, and policy-controlled signup journey for one application. Contract: GET /api/landing-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get application landing config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/landing-config/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### landing_config.update Create or update supplied landing-page fields for one application. Contract: PUT /api/landing-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "app_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_tagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_cta_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_cta_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hero_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "hero_badge_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_cta_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_cta_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "features": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "stats": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "integrations": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "testimonial_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "testimonial_avatar_initials": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "problem_statement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "solution_statement": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "app_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "cta_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "cta_subtitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pricing_enabled": { "type": "boolean" }, "pricing_tiers": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "footer_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "footer_links": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "legal_links": { "maxItems": 100, "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "show_topolo_one": { "type": "boolean" }, "is_enabled": { "type": "boolean" } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update application landing config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/landing-config/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### app_ui_config.get Read shared authenticated-shell colors and notes for one application. Contract: GET /api/app-ui-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get application UI config.", "additionalProperties": true } ``` Effects: Reads state through GET /api/app-ui-config/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### app_ui_config.update Update only supplied authenticated-shell fields for one application. Contract: PUT /api/app-ui-config/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "highlight_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "highlight_color_dark": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hint_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "hint_color_dark": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update application UI config.", "additionalProperties": true } ``` Effects: May change state through PUT /api/app-ui-config/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_events.list List a bounded page of scheduled login themes. Contract: GET /api/login-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "cursor": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "cursor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List login events.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### login_events.create Create a scheduled login theme for selected applications or the platform. Contract: POST /api/login-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "app_ids": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "null" } ] }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlay_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "lottie_animation_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "event_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "special_interaction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interaction_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create login event.", "additionalProperties": true } ``` Effects: May change state through POST /api/login-events. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_events.update Update supplied fields on one scheduled login theme. Contract: PUT /api/login-events/{eventId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "eventId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1 }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_global": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] }, "app_ids": { "anyOf": [ { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "null" } ] }, "start_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "end_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "theme_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "primary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "secondary_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "accent_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_start": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_gradient_end": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "background_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_video_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "background_animation": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "overlay_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "lottie_animation_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "event_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "special_interaction": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "interaction_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] }, "priority": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "enabled": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "eventId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update login event.", "additionalProperties": true } ``` Effects: May change state through PUT /api/login-events/{eventId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_events.delete Delete one scheduled login theme. Contract: DELETE /api/login-events/{eventId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "eventId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "eventId": { "type": "string", "minLength": 1 } }, "required": [ "eventId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete login event.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/login-events/{eventId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_presets.list List a bounded page of reusable login theme presets. Contract: GET /api/login-presets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "cursor": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "cursor": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List login presets.", "additionalProperties": true } ``` Effects: Reads state through GET /api/login-presets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### login_presets.create Create a reusable login theme preset. Contract: POST /api/login-presets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "config": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "preview_image_url": { "anyOf": [ { "type": "string", "format": "uri" }, { "type": "null" } ] }, "config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string" } ] }, "category": { "type": "string", "minLength": 1 }, "tags": { "anyOf": [ { "maxItems": 100, "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "string" } ] } }, "required": [ "name", "config" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create login preset.", "additionalProperties": true } ``` Effects: May change state through POST /api/login-presets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### login_presets.delete Delete one non-system login theme preset. Contract: DELETE /api/login-presets/{presetId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "presetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presetId": { "type": "string", "minLength": 1 } }, "required": [ "presetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete login preset.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/login-presets/{presetId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### platform_pricing.get Read the platform-wide pricing configuration. Contract: GET /api/admin/platform-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get platform pricing.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/platform-pricing without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### platform_pricing.update Update the platform-wide pricing configuration. Contract: PUT /api/admin/platform-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "base": { "planId": "example", "monthlyCentsPerSeat": 1 }, "includedFreeInBase": [ { "appId": "example", "headline": "example" } ], "platformCapabilities": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "base": { "type": "object", "properties": { "planId": { "type": "string", "minLength": 1 }, "monthlyCentsPerSeat": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "minimumSeats": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "seatTiers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo", "unitAmountCents" ], "additionalProperties": false } } }, "required": [ "planId", "monthlyCentsPerSeat" ], "additionalProperties": false }, "includedFreeInBase": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "headline": { "type": "string", "minLength": 1 }, "marketingPath": { "type": "string", "minLength": 1 } }, "required": [ "appId", "headline" ], "additionalProperties": false } }, "platformCapabilities": { "maxItems": 1000, "type": "array", "items": { "type": "string" } }, "platformTagline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schemaVersion": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update platform pricing.", "additionalProperties": true } ``` Effects: May change state through PUT /api/admin/platform-pricing. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### app_pricing_plans.list List pricing plans registered for one application. Contract: GET /api/admin/pricing-plans/by-app/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List application pricing plans.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/pricing-plans/by-app/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### app_pricing_plans.bulk_register Create or update a bounded set of application pricing plans. Contract: POST /api/admin/pricing-plans/bulk-register Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "plans": [ { "id": "demo_monthly", "displayName": "Demo Monthly", "pricingModel": "flat" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "plans": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "appId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "developerOrgId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1 }, "pricingModel": { "type": "string", "enum": [ "free", "included", "flat", "per_seat", "per_seat_tiered", "metered", "metered_tiered", "flat_plus_metered", "one_time" ] }, "unitLabel": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "billingCurrency": { "type": "string", "minLength": 1 }, "billingInterval": { "anyOf": [ { "type": "string", "enum": [ "day", "week", "month", "year" ] }, { "type": "null" } ] }, "isDefault": { "type": "boolean" }, "revShareBps": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "pricingDetails": { "type": "object", "properties": { "productName": { "type": "string", "minLength": 1 }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "tiers": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "upTo": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, { "type": "string", "const": "inf" } ] }, "unitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "upTo" ], "additionalProperties": false } }, "tiersMode": { "type": "string", "enum": [ "graduated", "volume" ] }, "meteredUnitAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "flatBaseAmountCents": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "required": [ "id", "displayName", "pricingModel" ], "additionalProperties": false } } }, "required": [ "plans" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk register application pricing plans.", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/pricing-plans/bulk-register. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### app_pricing_meters.register Create or update application usage meters and plan quotas. Contract: POST /api/admin/billing/register-app-pricing Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "meters": [ { "key": "example", "displayName": "example", "unit": "example" } ], "quotas": [ { "pricingPlanId": "example", "meterKey": "example", "includedPerSeat": 1, "includedFlat": 1 } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "meters": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "unit": { "type": "string", "minLength": 1 }, "billPerN": { "type": "number", "exclusiveMinimum": 0 }, "ttuMultipliers": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "number", "exclusiveMinimum": 0 } } }, "required": [ "key", "displayName", "unit" ], "additionalProperties": false } }, "quotas": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "pricingPlanId": { "type": "string", "minLength": 1 }, "meterKey": { "type": "string", "minLength": 1 }, "includedPerSeat": { "type": "number", "minimum": 0 }, "includedFlat": { "type": "number", "minimum": 0 }, "overagePriceId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "defaultHardCapMultiplier": { "anyOf": [ { "type": "number", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "pricingPlanId", "meterKey", "includedPerSeat", "includedFlat" ], "additionalProperties": false } } }, "required": [ "appId", "meters", "quotas" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Register application pricing meters.", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/billing/register-app-pricing. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### resource_grants.list_mine List a bounded page of the caller's live resource grants. Contract: GET /api/resource-grants/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "00000000-0000-4000-8000-000000000000", "app_id": "00000000-0000-4000-8000-000000000000", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "cursor": { "type": "string", "pattern": "^\\d+:[A-Za-z0-9_-]+$" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List my resource grants.", "additionalProperties": true } ``` Effects: Reads state through GET /api/resource-grants/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### resource_grants.create Grant a user access to one application resource when the caller can manage the organization or target application grants. Contract: POST /api/resource-grants Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "example", "appId": "example", "resourceType": "example", "resourceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "minLength": 1 }, "grantType": { "type": "string", "minLength": 1 }, "expiresAt": { "anyOf": [ { "type": "number" }, { "type": "string" }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "organizationId", "appId", "resourceType", "resourceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create resource grant.", "additionalProperties": true } ``` Effects: May change state through POST /api/resource-grants. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### resource_grants.revoke Revoke one resource grant when the caller can manage its organization. Contract: POST /api/resource-grants/{grantId}/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "grantId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "grantId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "grantId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke resource grant.", "additionalProperties": true } ``` Effects: May change state through POST /api/resource-grants/{grantId}/revoke. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### resource_grants.promote Promote a scoped user to an organization member when the caller can manage the organization or target application grants. Contract: POST /api/resource-grants/promote Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Promote resource-grant user.", "additionalProperties": true } ``` Effects: May change state through POST /api/resource-grants/promote. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.list List active canonical workspaces the caller may use in one application and organization. Contract: GET /api/workspaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "org_acme", "app_id": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "org_id", "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List workspaces.", "additionalProperties": true } ``` Effects: Reads canonical workspace identity, ownership, access, and default state from Topolo Auth. Verification: Use only workspace ids returned for the requested app_id and org_id. Confirm exactly one active workspace is marked as the application default. Recovery: Refresh the active organization and application context before retrying discovery. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. ### workspaces.create Create one canonical workspace for an application and organization. Contract: POST /api/workspaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "organizationId": "org_acme", "appId": "app_topolo_campaigns", "name": "Launch operations" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "isDefault": { "type": "boolean" } }, "required": [ "organizationId", "appId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create workspace.", "additionalProperties": true } ``` Effects: Creates canonical workspace identity in Topolo Auth. Makes the first active workspace the default, or honors isDefault when explicitly requested. Verification: Run workspaces.list for the same application and organization and confirm the new id appears once. Confirm the returned stable slug is not reused as the display name. Recovery: Refresh workspace discovery before retrying so a successful response is not duplicated after a network timeout. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. ### workspaces.rename Rename canonical workspace presentation without changing its stable id or slug. Contract: PATCH /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "name": "Customer launch" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 } }, "required": [ "workspaceId", "organizationId", "appId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Rename workspace.", "additionalProperties": true } ``` Effects: Changes only the canonical display name. Preserves the workspace id, slug, ownership, membership, and application data. Verification: Run workspaces.list and confirm the new name is returned for the same workspace id. Confirm app-local resources remain scoped to the unchanged workspace id. Recovery: Rediscover the workspace before retrying if ownership or organization context changed. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. ### workspaces.default.set Set the single canonical default workspace for an application and organization. Contract: PUT /api/workspaces/{workspaceId}/default Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId", "organizationId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set default workspace.", "additionalProperties": true } ``` Effects: Atomically makes this the only active default workspace for the application and organization. Verification: Run workspaces.list and confirm exactly this workspace is marked as default. Recovery: Do not infer default state after a conflict; rediscover it from Topolo Auth. 400 VALIDATION_ERROR: Correct the closed input schema and retry. 401 UNAUTHORIZED: Authenticate as the user acting in this workspace. 403 FORBIDDEN: Use an application and organization the caller may access; do not widen the caller role. 404 NOT_FOUND: Refresh canonical workspace discovery and confirm the workspace is still active. 409 CONFLICT: Refresh canonical workspace state and retry only if this workspace should still become the default. ### workspace_access.list_mine List active workspaces the caller may access in one application and organization. Contract: GET /api/workspace-access/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "org_acme", "app_id": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "org_id", "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List accessible workspaces.", "additionalProperties": true } ``` Effects: Reads the caller-specific workspace projection without changing access. Verification: Confirm data.accessMode is all only for organization owner, super admin, or platform break-glass authority. Use only resource ids returned in data.resources for subsequent workspace-scoped actions. Recovery: Refresh the active organization context and repeat discovery before retrying a denied workspace action. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_access.members.list List the owner, explicit members, and eligible same-organization assignees for one workspace. Contract: GET /api/workspace-access/{resourceId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "resourceId": "workspace_123", "org_id": "org_acme", "app_id": "app_topolo_campaigns" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "org_id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 } }, "required": [ "resourceId", "org_id", "app_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List workspace members.", "additionalProperties": true } ``` Effects: Reads workspace ownership, member grants, and assignable same-organization users. Verification: Confirm data.owner.accessRole is owner and no data.members entry is marked owner. Select grant and transfer targets only from data.assignableUsers or data.members. Recovery: Run workspace_access.list_mine and retry with a currently accessible workspace. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_access.members.grant Grant an active same-organization app member access to one workspace. Contract: POST /api/workspace-access/{resourceId}/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "resourceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "userId": "usr_member", "scope": "read_write" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "scope": { "type": "string", "enum": [ "read", "read_write", "admin" ] } }, "required": [ "resourceId", "organizationId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Grant workspace access.", "additionalProperties": true } ``` Effects: Creates or reactivates one workspace member grant. Does not create organization membership, app entitlement, a seat, or ownership. Verification: Run workspace_access.members.list and confirm the target user appears once in data.members. Validate a workspace-scoped request as the target user before treating access as complete. Recovery: Confirm the target already belongs to the organization and has app access, then retry without provisioning a new identity. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_access.members.revoke Revoke one explicit workspace member grant without changing organization membership. Contract: POST /api/workspace-access/{resourceId}/members/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "resourceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "userId": "usr_member", "reason": "Campaign complete" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "resourceId", "organizationId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke workspace access.", "additionalProperties": true } ``` Effects: Revokes the target user explicit access to this workspace. Does not remove organization membership, app entitlement, a seat, or access to other workspaces. Verification: Run workspace_access.members.list and confirm the target is absent from data.members. Confirm a workspace-scoped request by the target is denied unless they hold an organization-wide override. Recovery: If the user is the current owner, transfer ownership first; owner access cannot be revoked as a member grant. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. ### workspace_ownership.transfer Atomically transfer the single primary owner role to an active same-organization app member. Contract: POST /api/workspace-access/{resourceId}/transfer Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "resourceId": "workspace_123", "organizationId": "org_acme", "appId": "app_topolo_campaigns", "newOwnerUserId": "usr_new_owner", "retainPreviousOwnerAccess": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "resourceId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "newOwnerUserId": { "type": "string", "minLength": 1 }, "retainPreviousOwnerAccess": { "type": "boolean" } }, "required": [ "resourceId", "organizationId", "appId", "newOwnerUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Transfer workspace ownership.", "additionalProperties": true } ``` Effects: Replaces the single workspace owner in one atomic update. Removes any redundant member grant for the new owner. Retains the previous owner as an admin-scoped member unless retainPreviousOwnerAccess is false. Verification: Run workspace_access.members.list and confirm the new owner is data.owner. Confirm exactly one owner and check whether the previous owner remains in data.members as requested. Recovery: Do not retry blindly after a conflict; rediscover the current owner and require a fresh transfer decision. 400 VALIDATION_ERROR: Correct the field identified by the closed input schema and retry. 403 FORBIDDEN: Use the workspace owner or an organization owner or super admin; do not widen the caller role. 404 NOT_FOUND: Refresh workspace discovery and confirm the workspace still exists in this application and organization. 409 CONFLICT: Refresh workspace members because ownership changed, then retry only if the transfer is still intended. ### me.get Read the caller's current Auth identity, context, and optional service permissions. Contract: GET /api/me Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my Auth profile.", "additionalProperties": true } ``` Effects: Reads state through GET /api/me without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### me.tenant.get Read the organization selected by the caller's credential-bound context. Contract: GET /api/tenant Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my organization.", "additionalProperties": true } ``` Effects: Reads state through GET /api/tenant without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### me.recovery_email.get Read the caller's personal recovery email status. Contract: GET /api/me/recovery-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get my recovery email.", "additionalProperties": true } ``` Effects: Reads state through GET /api/me/recovery-email without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### me.recovery_email.request_verification Set the caller's personal recovery email and send a verification request. Contract: POST /api/me/recovery-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "email": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "email" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Request recovery email verification.", "additionalProperties": true } ``` Effects: May change state through POST /api/me/recovery-email. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### me.sessions.revoke_all Revoke every access token, refresh token, and session belonging to the caller. Contract: POST /api/auth/logout-everywhere Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke all my sessions.", "additionalProperties": true } ``` Effects: May change state through POST /api/auth/logout-everywhere. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.list Read users visible to the authenticated Auth principal. Contract: GET /api/users Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List users.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### users.get Read one user and their visible security state. Contract: GET /api/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### users.export Export the portable Auth-owned identity, access, preference, session, and audit record set for one user. Contract: GET /api/users/{userId}/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Export user identity data.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_users.list List users in one organization, including deleted organizations when explicitly requested. Contract: GET /api/users/organization/{orgId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "includeDeletedOrganizations": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization users.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/organization/{orgId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### users.create Create a user in an organization managed by the caller. Contract: POST /api/users Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "email": "user@example.com", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "email": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "orgId": { "type": "string", "minLength": 1 }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "password": { "type": "string", "minLength": 8 } }, "required": [ "email", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create user.", "additionalProperties": true } ``` Effects: May change state through POST /api/users. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.update Update one user profile or organization role. Contract: PUT /api/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update user.", "additionalProperties": true } ``` Effects: May change state through PUT /api/users/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.status.update Activate or suspend one user. Contract: PATCH /api/users/{userId}/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "isActive": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "isActive": { "type": "boolean" } }, "required": [ "userId", "isActive" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update user status.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/users/{userId}/status. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.delete Soft-delete one user, revoke their sessions, and release their email address. Contract: DELETE /api/users/{userId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.delete_permanently Permanently purge Auth-owned data for one deleted user. Contract: DELETE /api/users/{userId}/permanent Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Permanently delete user.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/permanent. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_permissions.get Evaluate one user's effective permissions, optionally for one service. Contract: GET /api/users/{userId}/permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "service": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/permissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_permission_overrides.list List explicit allow and deny overrides for one user. Contract: GET /api/users/{userId}/service-permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user permission overrides.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/service-permissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_permission_overrides.create Create an explicit service permission allow or deny override for one user. Contract: POST /api/users/{userId}/service-permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "orgId": "example", "appId": "example", "permissionName": "example", "effect": "allow" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "permissionName": { "type": "string", "minLength": 1 }, "effect": { "type": "string", "enum": [ "allow", "deny" ] }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "userId", "orgId", "appId", "permissionName", "effect" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create user permission override.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/service-permissions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_permission_overrides.delete Delete one explicit user permission override. Contract: DELETE /api/users/{userId}/service-permissions/{overrideId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "overrideId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "overrideId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "overrideId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user permission override.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/service-permissions/{overrideId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_service_access.get Read one user's effective application access and seat assignments. Contract: GET /api/users/{userId}/service-access Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "appSwitcherOnly": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user service access.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/service-access without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_service_access.replace Replace one user's assigned applications across organization-enabled services. Contract: PUT /api/users/{userId}/service-access Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "appIds": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "appSwitcherOnly": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] }, "appIds": { "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "userId", "appIds" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace user service access.", "additionalProperties": true } ``` Effects: May change state through PUT /api/users/{userId}/service-access. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sessions.list Read sessions for the caller or a managed user. Contract: GET /api/users/{userId}/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user sessions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/sessions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sessions.delete Revoke one session belonging to the caller or a managed user. Contract: DELETE /api/users/{userId}/sessions/{sessionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user session.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/sessions/{sessionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_oauth_providers.list List external sign-in providers linked to one visible user. Contract: GET /api/users/{userId}/oauth-providers Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user OAuth providers.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/oauth-providers without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_oauth_providers.unlink Unlink one external sign-in provider from a visible user. Contract: DELETE /api/users/{userId}/oauth-providers/{provider} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "provider": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 } }, "required": [ "userId", "provider" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Unlink user OAuth provider.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/oauth-providers/{provider}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### users.unlock Clear the failed-login lockout for one managed user. Contract: POST /api/users/{userId}/unlock Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Unlock user account.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/unlock. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.mfa_protection.canary Verify that every retained MFA secret is protected and every backup code is hash-only. Contract: GET /api/admin/privacy/mfa-protection/canary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Check Auth MFA protection.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/privacy/mfa-protection/canary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_security.get Read MFA, passkey, backup-code, and account-lock status for one visible user. Contract: GET /api/users/{userId}/2fa-status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get user security status.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/2fa-status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_mfa.setup Create a time-limited MFA setup secret, QR code, backup codes, and verification token. Contract: POST /api/users/{userId}/mfa/setup Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Begin user MFA setup.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/mfa/setup. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_mfa.verify Verify a TOTP code and enable MFA for one user. Contract: POST /api/users/{userId}/mfa/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "token": "example", "setupToken": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "setupToken": { "type": "string", "minLength": 1 } }, "required": [ "userId", "token", "setupToken" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Verify user MFA setup.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/mfa/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_mfa.disable Disable MFA for one visible user. Contract: DELETE /api/users/{userId}/mfa Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Disable user MFA.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/mfa. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_mfa.backup_codes.regenerate Replace and return the one-time backup codes for an MFA-enabled user. Contract: POST /api/users/{userId}/backup-codes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Regenerate user backup codes.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/backup-codes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_passkeys.registration.begin Create WebAuthn registration options for one user. Contract: POST /api/users/{userId}/passkeys/setup Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Begin passkey registration.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/passkeys/setup. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_passkeys.registration.complete Verify and store a WebAuthn credential for one user. Contract: POST /api/users/{userId}/passkeys/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "credential": {}, "challengeId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "credential": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "challengeId": { "type": "string", "minLength": 1 }, "friendlyName": { "type": "string", "minLength": 1 } }, "required": [ "userId", "credential", "challengeId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete passkey registration.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/passkeys/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_passkeys.list List sanitized passkey credentials for one visible user. Contract: GET /api/users/{userId}/passkeys Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 } }, "required": [ "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List user passkeys.", "additionalProperties": true } ``` Effects: Reads state through GET /api/users/{userId}/passkeys without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### user_passkeys.delete Delete one passkey credential belonging to a visible user. Contract: DELETE /api/users/{userId}/passkeys/{passkeyId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "userId": "example", "passkeyId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "passkeyId": { "type": "string", "minLength": 1 } }, "required": [ "userId", "passkeyId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete user passkey.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/users/{userId}/passkeys/{passkeyId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_password.change Change the caller's password after verifying their current password. Contract: POST /api/users/{userId}/password Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "currentPassword": "examplex", "newPassword": "examplex" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "currentPassword": { "type": "string", "minLength": 8 }, "newPassword": { "type": "string", "minLength": 8 } }, "required": [ "userId", "currentPassword", "newPassword" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Change my password.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/password. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_password.set_initial Establish the caller's first password for a passwordless account. Contract: POST /api/users/{userId}/password/initial Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "newPassword": "examplex" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "newPassword": { "type": "string", "minLength": 8 } }, "required": [ "userId", "newPassword" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set my initial password.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/password/initial. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### user_password.admin_reset Set a new password for one user managed by the caller. Contract: POST /api/users/{userId}/password/admin-reset Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: users:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "userId": "example", "newPassword": "examplex" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "userId": { "type": "string", "minLength": 1 }, "newPassword": { "type": "string", "minLength": 8 } }, "required": [ "userId", "newPassword" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reset user password.", "additionalProperties": true } ``` Effects: May change state through POST /api/users/{userId}/password/admin-reset. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### api_keys.options List the applications scopes and resources the caller may bind to a new API key. Contract: GET /api/api-keys/options Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "minLength": 1 }, "data": { "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "canCreate": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "app_id", "name" ], "additionalProperties": {} } }, "organizationWideScopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "app_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id", "app_id", "name" ], "additionalProperties": {} } }, "resourceTypes": { "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "emptyLabel": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "label", "emptyLabel" ], "additionalProperties": {} } }, "resources": { "type": "array", "items": { "type": "object", "properties": { "resource_type": { "type": "string", "minLength": 1 }, "resource_id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "accessLevel": { "type": "string", "minLength": 1 }, "allowedScopes": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "resource_type", "resource_id", "label", "status", "accessLevel", "allowedScopes" ], "additionalProperties": {} } } }, "required": [ "organizationId", "appId", "serviceName", "canCreate", "scopes", "organizationWideScopes", "resourceTypes", "resources" ], "additionalProperties": false }, "timestamp": { "type": "string", "minLength": 1 } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Returns only applications scopes and resources currently available to the authenticated caller. Verification: Use the returned allowedScopes without widening them before planning api_keys.create. Recovery: 400 VALIDATION_ERROR: Correct the application or organization identifier and retry. 403 FORBIDDEN: Use an application and organization visible to the authenticated caller. ### api_keys.list List central API keys visible to the caller. Contract: GET /api/api-keys Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List API keys.", "additionalProperties": true } ``` Effects: Reads state through GET /api/api-keys without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### api_keys.create Create a credential scoped to one organization, application, permission set, and optional resources. Contract: POST /api/api-keys Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_campaigns", "name": "Staging demo agent", "scopes": [ "workspaces:read" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "scopes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, "resourceBindings": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "resourceId" ], "additionalProperties": false } }, "expiresInDays": { "type": "number", "minimum": 0 } }, "required": [ "appId", "name", "scopes" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string", "minLength": 1 }, "data": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "organizationSlug": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "scopes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, "resourceBindings": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "resourceId" ], "additionalProperties": false } }, "expiresAt": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "createdAt": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string", "const": "active" }, "secret": { "type": "string", "minLength": 1 } }, "required": [ "id", "name", "organizationId", "organizationSlug", "appId", "scopes", "resourceBindings", "expiresAt", "createdAt", "status", "secret" ], "additionalProperties": false } }, "required": [ "key" ], "additionalProperties": false }, "timestamp": { "type": "string", "minLength": 1 } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Creates one API key for the requested application, scopes, and resource bindings. Returns the plaintext API key secret exactly once in data.key.secret. Verification: Store data.key.secret in the intended secret manager because it cannot be retrieved again. Inject the secret as TOPOLO_API_KEY in an isolated process and run topolo whoami --json. Run topolo resources for data.key.appId and confirm only the intended resource bindings are returned. Recovery: 400 VALIDATION_ERROR: Correct the reported field using the published input schema and retry. 403 FORBIDDEN: Use an authorized organization, application, scope, and resource selection; do not widen access automatically. 500 SERVER_ERROR: Preserve the request id and retry only after the platform error is resolved. ### api_keys.update Update the name, scopes, resource bindings, or expiry of one API key. Contract: PUT /api/api-keys/{apiKeyId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "apiKeyId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "apiKeyId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "scopes": { "minItems": 1, "maxItems": 1000, "type": "array", "items": { "type": "string", "minLength": 1 } }, "resourceBindings": { "maxItems": 1000, "type": "array", "items": { "type": "object", "properties": { "resourceType": { "type": "string", "minLength": 1 }, "resourceId": { "type": "string", "minLength": 1 } }, "required": [ "resourceType", "resourceId" ], "additionalProperties": false } }, "expiresInDays": { "type": "number", "minimum": 0 } }, "required": [ "apiKeyId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update API key.", "additionalProperties": true } ``` Effects: May change state through PUT /api/api-keys/{apiKeyId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### api_keys.revoke Revoke one central API key. Contract: POST /api/api-keys/{apiKeyId}/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: api_keys:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "apiKeyId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "apiKeyId": { "type": "string", "minLength": 1 } }, "required": [ "apiKeyId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke API key.", "additionalProperties": true } ``` Effects: May change state through POST /api/api-keys/{apiKeyId}/revoke. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sso_exchange_diagnostics.list Inspect sanitized handoff-to-exchange timing, replay outcomes, failures, and request correlation within the caller-visible organization. Contract: GET /api/sso/exchange-diagnostics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: sessions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "org_acme", "requestId": "3f9c867d-0c1e-4ec7-9aaf-8f74be533b61", "limit": 25 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "requestId": { "type": "string", "minLength": 1 }, "outcome": { "type": "string", "enum": [ "pending", "redeemed", "replayed", "denied", "failed" ] }, "since": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "until": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "exchanges": { "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "exchangeId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "appId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organizationId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "redirectOrigin": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "createdAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "codeExpiresAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "firstExchangeAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lastExchangeAt": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "firstRequestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastRequestId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exchangeAttemptCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "replayCount": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "outcome": { "type": "string", "enum": [ "pending", "redeemed", "replayed", "denied", "failed" ] }, "errorCode": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handoffToFirstExchangeMs": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "updatedAt": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "exchangeId", "userId", "appId", "organizationId", "redirectOrigin", "createdAt", "codeExpiresAt", "firstExchangeAt", "lastExchangeAt", "firstRequestId", "lastRequestId", "exchangeAttemptCount", "replayCount", "outcome", "errorCode", "handoffToFirstExchangeMs", "updatedAt" ], "additionalProperties": false } }, "total": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "exchanges", "total", "limit", "offset" ], "additionalProperties": false }, "timestamp": { "type": "string" } }, "required": [ "success", "message", "data", "timestamp" ], "additionalProperties": false } ``` Effects: Reads a seven-day sanitized exchange diagnostic ledger without returning codes, hashes, tokens, redirect paths, or cached user payloads. Verification: Confirm every returned organizationId matches the requested organization or the caller active organization. When requestId is supplied, confirm it equals each row firstRequestId or lastRequestId. Use createdAt, firstExchangeAt, lastExchangeAt, handoffToFirstExchangeMs, outcome, and errorCode together when diagnosing exchange timing or failure. Recovery: Narrow by organization, application, request ID, outcome, or time window; diagnostics older than seven days are intentionally unavailable. 400 VALIDATION_ERROR: Correct the closed filter schema or time range and retry. 401 AUTH_ERROR: Refresh the caller session or credential before retrying. 403 FORBIDDEN: Use sessions:read within the active organization; do not widen the requested tenant. ### admin.stats Read Auth admin dashboard statistics. Contract: GET /api/admin/stats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get Auth admin stats.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/stats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.system_health Read Auth system health status. Contract: GET /api/admin/system-health Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "cursor": "app_topolo_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 50 }, "cursor": { "type": "string", "pattern": "^app_[a-z0-9]+(?:_[a-z0-9]+)+$" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get Auth system health.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/system-health without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### audit_logs.list Read Auth audit log entries. Contract: GET /api/audit-logs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "action": "example", "organization": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "action": { "type": "string", "minLength": 1 }, "organization": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "offset": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List audit logs.", "additionalProperties": true } ``` Effects: Reads state through GET /api/audit-logs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.recent_activity Read recent activity recorded by the Auth control plane. Contract: GET /api/admin/recent-activity Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: audit:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get recent Auth activity.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/recent-activity without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### services.list List services registered with the Auth control plane. Contract: GET /api/services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "cursor": "app_topolo_example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "string", "pattern": "^app_[a-z0-9]+(?:_[a-z0-9]+)+$" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List services.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### services.get Read one registered service by canonical application id. Contract: GET /api/services/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get service.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### services.create Create a platform-managed service registration. Contract: POST /api/services Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "base_url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "base_url": { "type": "string", "format": "uri" }, "version": { "type": "string", "minLength": 1 }, "api_key_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "show_in_app_switcher": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "name", "base_url" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create service.", "additionalProperties": true } ``` Effects: May change state through POST /api/services. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### services.update Update a platform-managed service registration. Contract: PUT /api/services/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "base_url": { "type": "string", "format": "uri" }, "version": { "type": "string", "minLength": 1 }, "api_key_hash": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "status": { "type": "string", "enum": [ "active", "inactive", "deleted" ] }, "show_in_app_switcher": { "anyOf": [ { "type": "boolean" }, { "type": "integer", "minimum": 0, "maximum": 1 } ] } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update service.", "additionalProperties": true } ``` Effects: May change state through PUT /api/services/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### services.delete Delete a platform-managed service registration. Contract: DELETE /api/services/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete service.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/services/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_permissions.list List permissions declared by one service. Contract: GET /api/services/{appId}/permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/permissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_api_key_scopes.list List API key scopes exposed by one service. Contract: GET /api/services/{appId}/api-key-scopes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service API key scopes.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/api-key-scopes without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_api_key_resources.list List credential-bindable resources exposed by one service. Contract: GET /api/services/{appId}/api-key-resources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service API key resources.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/api-key-resources without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_permissions.create Create a permission for one platform-managed service. Contract: POST /api/services/{appId}/permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "name": "2026-01-01" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9:_-]+$" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "appId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create service permission.", "additionalProperties": true } ``` Effects: May change state through POST /api/services/{appId}/permissions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_permissions.update Update one service permission. Contract: PUT /api/permissions/{permissionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "permissionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "permissionId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "pattern": "^[a-zA-Z0-9:_-]+$" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "resource_pattern": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "permissionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update service permission.", "additionalProperties": true } ``` Effects: May change state through PUT /api/permissions/{permissionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_permissions.delete Delete one service permission. Contract: DELETE /api/permissions/{permissionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: permissions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "permissionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "permissionId": { "type": "string", "minLength": 1 } }, "required": [ "permissionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete service permission.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/permissions/{permissionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_role_permissions.get Read a service role permission bundle. Contract: GET /api/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example", "role": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 } }, "required": [ "appId", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get service role permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/role-permissions/{role} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_role_permissions.replace Replace the permission bundle for a service role. Contract: PUT /api/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "role": "example", "permissions": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permissions": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "appId", "role", "permissions" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace service role permissions.", "additionalProperties": true } ``` Effects: May change state through PUT /api/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_role_permissions.add Add one permission to a service role. Contract: POST /api/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add service role permission.", "additionalProperties": true } ``` Effects: May change state through POST /api/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_role_permissions.remove Remove one permission from a service role. Contract: DELETE /api/services/{appId}/role-permissions/{role}/{permission} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove service role permission.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/services/{appId}/role-permissions/{role}/{permission}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_roles.list List the operator roles declared by one service. Contract: GET /api/services/{appId}/declared-roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List declared service roles.", "additionalProperties": true } ``` Effects: Reads state through GET /api/services/{appId}/declared-roles without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_roles.list List roles defined for one organization. Contract: GET /api/organizations/{orgId}/roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List organization roles.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/roles without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_roles.create Create a custom role for one organization. Contract: POST /api/organizations/{orgId}/roles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "displayName": { "type": "string", "minLength": 1 }, "description": { "anyOf": [ { "type": "string", "maxLength": 240 }, { "type": "null" } ] }, "templateRoleKey": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create organization role.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/roles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_roles.delete Delete one custom organization role. Contract: DELETE /api/organizations/{orgId}/roles/{roleKey} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete organization role.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/roles/{roleKey}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_services.install Install or update access to an application for one organization. Contract: POST /api/organizations/{orgId}/services/{appId}/install Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "enum": [ "everyone", "me", "users" ] }, "userIds": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "user_ids": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Install organization service.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/install. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_seats.get Read seat pools and usage across an organization. Contract: GET /api/organizations/{orgId}/seats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 } }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization seat summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/seats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_seats.get Read one service seat pool and its assignees. Contract: GET /api/organizations/{orgId}/services/{appId}/seats Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get service seats.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/seats without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_seats.assign Assign an application seat to an organization member. Contract: POST /api/organizations/{orgId}/services/{appId}/seats/assign Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Assign service seat.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/seats/assign. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_seats.revoke Revoke an application seat from an organization member. Contract: POST /api/organizations/{orgId}/services/{appId}/seats/revoke Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "userId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "userId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "userId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke service seat.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/seats/revoke. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_seats.reseat Move an application seat between organization members. Contract: POST /api/organizations/{orgId}/services/{appId}/seats/reseat Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: organizations:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "fromUserId": "example", "toUserId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "fromUserId": { "type": "string", "minLength": 1 }, "toUserId": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "fromUserId", "toUserId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reassign service seat.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/seats/reseat. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_services.request_access Request access to an application from organization administrators. Contract: POST /api/organizations/{orgId}/services/{appId}/access-request Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: services:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "maxLength": 500 } }, "required": [ "orgId", "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Request service access.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/access-request. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_role_permissions.get Read one organization role permission bundle for an application. Contract: GET /api/organizations/{orgId}/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "orgId": "example", "appId": "example", "role": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "role" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization role permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{orgId}/services/{appId}/role-permissions/{role} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organization_role_permissions.replace Replace one organization role permission bundle for an application. Contract: PUT /api/organizations/{orgId}/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "role": "example", "permissions": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permissions": { "maxItems": 500, "type": "array", "items": { "type": "string", "minLength": 1 } }, "included": { "type": "boolean" } }, "required": [ "orgId", "appId", "role", "permissions" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Replace organization role permissions.", "additionalProperties": true } ``` Effects: May change state through PUT /api/organizations/{orgId}/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_role_permissions.add Add one application permission to an organization role. Contract: POST /api/organizations/{orgId}/services/{appId}/role-permissions/{role} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add organization role permission.", "additionalProperties": true } ``` Effects: May change state through POST /api/organizations/{orgId}/services/{appId}/role-permissions/{role}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organization_role_permissions.remove Remove one application permission from an organization role. Contract: DELETE /api/organizations/{orgId}/services/{appId}/role-permissions/{role}/{permission} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roles:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "orgId": "example", "appId": "example", "role": "example", "permission": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "role": { "type": "string", "minLength": 1 }, "permission": { "type": "string", "minLength": 1 } }, "required": [ "orgId", "appId", "role", "permission" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove organization role permission.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{orgId}/services/{appId}/role-permissions/{role}/{permission}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for Docs. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.bootstrap Get the authenticated Docs user and organization context. Contract: GET /api/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/bootstrap without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.get Get the active Docs workspace projection. Contract: GET /api/docs/workspace Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/workspace without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.archive Archive an empty Docs workspace and purge its archived Docs data. Contract: DELETE /api/docs/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.list List active documentation spaces in the selected workspace. Contract: GET /api/docs/spaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.create Create a tenant-isolated documentation space. Contract: POST /api/docs/spaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "slug": "example", "description": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace", "public" ] }, "defaultLocale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "brand": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/spaces. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.get Get one documentation space from the selected workspace. Contract: GET /api/docs/spaces/{spaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces/{spaceId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.update Update a documentation space, visibility, locale, or brand configuration. Contract: PATCH /api/docs/spaces/{spaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace", "public" ] }, "defaultLocale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "brand": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/docs/spaces/{spaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.archive Archive a documentation space and remove it from active workspace navigation. Contract: DELETE /api/docs/spaces/{spaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/spaces/{spaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.documents.list List active documents in one documentation space. Contract: GET /api/docs/spaces/{spaceId}/documents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces/{spaceId}/documents without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.documents.create Create a document and its first immutable locale version. Contract: POST /api/docs/spaces/{spaceId}/documents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "title": { "type": "string" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "bodyMarkdown": { "type": "string" }, "locale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "sourceKind": { "type": "string", "enum": [ "native", "platform_repo", "repository_sync", "generated" ] }, "sourceRevision": { "type": "string" }, "sourcePath": { "type": "string" } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/spaces/{spaceId}/documents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.sections.list List the configurable top-level sections a documentation space is organized into. Contract: GET /api/docs/spaces/{spaceId}/sections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces/{spaceId}/sections without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.sections.create Create a top-level navigation section in one documentation space. Contract: POST /api/docs/spaces/{spaceId}/sections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/spaces/{spaceId}/sections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.sections.reorder Set the display order of every section in one documentation space. Contract: POST /api/docs/spaces/{spaceId}/sections/reorder Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "space_example", "sectionIds": [ "section_intro", "section_reference" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sectionIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "minItems": 1 } }, "required": [ "spaceId", "sectionIds" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Replaces the complete section display order for one documentation space. Verification: Call spaces.sections.list for the same spaceId and confirm the returned section order matches sectionIds. Recovery: 400 invalid_section_order: List the space sections and submit every section id exactly once. 403 forbidden: Use a credential with docs:write access to the selected Docs workspace. ### sections.update Rename a documentation section or change its slug. Contract: PATCH /api/docs/sections/{sectionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "sectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sectionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "sectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/docs/sections/{sectionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sections.delete Delete a documentation section; its documents become unassigned rather than being deleted. Contract: DELETE /api/docs/sections/{sectionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "sectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sectionId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "sectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/sections/{sectionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.section.set Move a document into a section of its space, or unassign it, and set its position within that section. Contract: PUT /api/docs/documents/{documentId}/section Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sectionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/docs/documents/{documentId}/section. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.list List active documents across the selected workspace. Contract: GET /api/docs/documents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/documents without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### documents.get Get one document and its immutable version history. Contract: GET /api/docs/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/documents/{documentId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### documents.update Update native document metadata and review state. Contract: PATCH /api/docs/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "title": { "type": "string" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "review" ] } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/docs/documents/{documentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.archive Archive a native document and remove its publication pointer. Contract: DELETE /api/docs/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/documents/{documentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.versions.list List immutable versions for one document. Contract: GET /api/docs/documents/{documentId}/versions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/documents/{documentId}/versions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### documents.versions.create Create an immutable locale-specific version and update full-text retrieval. Contract: POST /api/docs/documents/{documentId}/versions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example", "bodyMarkdown": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "summary": { "type": "string" }, "bodyMarkdown": { "type": "string" }, "locale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "sourceRevision": { "type": "string" }, "sourcePath": { "type": "string" } }, "required": [ "documentId", "bodyMarkdown" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/documents/{documentId}/versions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.publish Publish one exact document version as an immutable public snapshot. Contract: POST /api/docs/documents/{documentId}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:publish Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/documents/{documentId}/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.unpublish Remove public lookup pointers for a document. Contract: POST /api/docs/documents/{documentId}/unpublish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:publish Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/documents/{documentId}/unpublish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### search.query Run tenant-filtered full-text search across current locale versions. Contract: GET /api/docs/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 500 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "q" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### public_search.query Search titles, summaries, and published body text in one public documentation space. Anonymous; only published versions are matched. Contract: GET /api/public/docs/{spaceSlug}/search.json Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceSlug": "example", "q": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceSlug": { "type": "string", "minLength": 1, "maxLength": 160 }, "q": { "type": "string", "minLength": 1, "maxLength": 500 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "spaceSlug", "q" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/public/docs/{spaceSlug}/search.json without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### search.ask Answer from tenant-filtered retrieved versions and return immutable citations. Contract: POST /api/docs/ask Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "query": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "query" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/ask. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace.export Export spaces, documents, versions, and publication metadata for the selected workspace. Contract: GET /api/docs/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:export Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### platform_corpus.sync Project the revisioned Topolo platform corpus into its platform-owned Docs workspace in an idempotent batch. Contract: POST /api/docs/platform-corpus/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "cursor": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/platform-corpus/sync. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.catalog_drift.record Persist a catalog drift result and notify the platform operator. Contract: POST /api/operations/catalog-drift Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: validation:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "source": "example", "expectedDigest": "example", "actualDigest": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "source": { "type": "string", "minLength": 1, "maxLength": 240 }, "expectedDigest": { "type": "string", "minLength": 1, "maxLength": 160 }, "actualDigest": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "runId", "source", "expectedDigest", "actualDigest" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/catalog-drift. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.link_checks.fail Persist a failed link validation result and notify the platform operator. Contract: POST /api/operations/link-checks/failed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: validation:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "checkedUrl": "https://example.com", "reason": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "checkedUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "statusCode": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 599 }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "runId", "checkedUrl", "reason" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/link-checks/failed. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.publishes.complete Persist a completed documentation publish and notify the platform operator. Contract: POST /api/operations/publishes/completed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "revision": "example", "environment": "development", "publishedUrl": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "string", "minLength": 1, "maxLength": 160 }, "environment": { "type": "string", "enum": [ "development", "staging", "production" ] }, "publishedUrl": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "runId", "revision", "environment", "publishedUrl" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/publishes/completed. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.publishes.fail Persist a failed documentation publish and notify the platform operator. Contract: POST /api/operations/publishes/failed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "revision": "example", "environment": "development", "reason": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "string", "minLength": 1, "maxLength": 160 }, "environment": { "type": "string", "enum": [ "development", "staging", "production" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "runId", "revision", "environment", "reason" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/publishes/failed. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Read the TopoloOne widget summary for Localize. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get widget summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### options.list Read available services, namespaces, locales, and catalog versions. Contract: GET /api/options Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List catalog options.", "additionalProperties": true } ``` Effects: Reads state through GET /api/options without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### entries.list Read joined source and translation entries for a catalog slice. Contract: GET /api/entries Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "namespace": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "q": { "type": "string" }, "state": { "type": "string", "minLength": 1 }, "limit": { "type": "string" }, "offset": { "type": "string" } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List translation entries.", "additionalProperties": true } ``` Effects: Reads state through GET /api/entries without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sources.list Read source strings for a service namespace. Contract: GET /api/sources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example", "namespace": "example", "q": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "namespace": { "type": "string", "minLength": 1 }, "q": { "type": "string" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List source strings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/sources without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### values.list Read translated values for a service namespace. Contract: GET /api/values Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example", "namespace": "example", "q": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "namespace": { "type": "string", "minLength": 1 }, "q": { "type": "string" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 }, "locale": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List translated values.", "additionalProperties": true } ``` Effects: Reads state through GET /api/values without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sources.upsert Create or update one Localize source string. Contract: PUT /api/sources Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "key": "example", "sourceText": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "sourceLocale": { "type": "string", "minLength": 1 }, "sourceHash": { "type": "string", "minLength": 1 }, "sourceText": { "type": "string", "minLength": 1 } }, "required": [ "appId", "key", "sourceText" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Upsert source string.", "additionalProperties": true } ``` Effects: May change state through PUT /api/sources. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sources.bulk_upsert Create or update a batch of Localize source strings. Contract: POST /api/sources/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "sources": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "sourceLocale": { "type": "string", "minLength": 1 }, "sources": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "type": "string" } } }, "required": [ "appId", "sources" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk upsert source strings.", "additionalProperties": true } ``` Effects: May change state through POST /api/sources/bulk. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### values.upsert Create or update one translated value. Contract: PUT /api/values Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "key": "example", "locale": "en-US", "value": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "key": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "sourceHash": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "generatedBy": { "type": "string", "minLength": 1 } }, "required": [ "appId", "key", "locale", "value" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Upsert translated value.", "additionalProperties": true } ``` Effects: May change state through PUT /api/values. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### values.bulk_upsert Create or update a batch of translated values. Contract: POST /api/values/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "locale": "en-US", "values": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "values": { "type": "object", "propertyNames": { "type": "string", "minLength": 1 }, "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } }, "sourceHash": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "generatedBy": { "type": "string", "minLength": 1 } }, "required": [ "appId", "locale", "values" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Bulk upsert translated values.", "additionalProperties": true } ``` Effects: May change state through POST /api/values/bulk. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### translations.generate Generate translated values for a service namespace. Contract: POST /api/translations/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "targetLocale": "en-US" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "targetLocale": { "type": "string", "minLength": 1 }, "namespace": { "type": "string", "minLength": 1 }, "sourceLocale": { "type": "string", "minLength": 1 }, "keys": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "missingOnly": { "type": "boolean" }, "missingOrStale": { "type": "boolean" }, "context": { "type": "string" }, "autoPublish": { "type": "boolean" } }, "required": [ "appId", "targetLocale" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate translations.", "additionalProperties": true } ``` Effects: May change state through POST /api/translations/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### reviews.request Request a human review of a translated catalog slice. Contract: POST /api/reviews Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "locale": "en-US" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "message": { "type": "string" } }, "required": [ "appId", "locale" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Request translation review.", "additionalProperties": true } ``` Effects: May change state through POST /api/reviews. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### catalogs.publish Publish a Localize catalog bundle for a service namespace and locale. Contract: POST /api/catalogs/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:publish Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "locale": "en-US" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "merge": { "anyOf": [ { "type": "boolean" }, { "type": "string", "enum": [ "true", "false" ] } ] }, "allowShrink": { "type": "boolean" }, "version": { "type": "string", "minLength": 1 }, "r2Key": { "type": "string", "minLength": 1 } }, "required": [ "appId", "locale" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Publish catalog.", "additionalProperties": true } ``` Effects: May change state through POST /api/catalogs/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sources.prune Remove source strings and orphan values outside a provided key set. Contract: POST /api/sources/prune Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "appId": "app_topolo_example", "keys": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "sourceLocale": { "type": "string", "minLength": 1 }, "keys": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "appId", "keys" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Prune source strings.", "additionalProperties": true } ``` Effects: May change state through POST /api/sources/prune. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### catalogs.index List and filter Localize catalog health and publication state. Contract: GET /api/catalog-index Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example", "appId": "example", "locale": "en-US" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "locale": { "type": "string", "minLength": 1 }, "health": { "type": "string", "enum": [ "all", "ready", "published", "missing", "needs_work" ] }, "limit": { "type": "string" }, "offset": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/catalog-index without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### catalogs.rekey Move current catalog objects onto canonical application ID storage keys. Contract: POST /api/admin/rekey Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:publish Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "dryRun": true, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "dryRun": { "type": "boolean" }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 300 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/rekey. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### catalogs.sync_from_staging Promote translated staging catalogs into the current production deployment. Contract: POST /api/admin/sync-from-staging Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:publish Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "maxPacks": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "maxPacks": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/sync-from-staging. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### autofill.enqueue Register source strings and enqueue missing translations for a service namespace. Contract: POST /api/autofill/enqueue Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: localize:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "app_topolo_example", "namespace": "example", "sources": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "pattern": "^(?:platform|app_[a-z0-9]+(?:_[a-z0-9]+)+)$" }, "namespace": { "type": "string", "minLength": 1 }, "sources": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "sourceLocale": { "type": "string", "minLength": 1 }, "locales": { "minItems": 1, "type": "array", "items": { "type": "string", "minLength": 1 } }, "sync": { "type": "boolean" } }, "required": [ "appId", "namespace", "sources" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/autofill/enqueue. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo Quro source contract Human reference: https://docs.topolo.app/systems/topolo-quro Machine reference: https://docs.topolo.app/machine/systems/topolo-quro.json Source revisions: apps/TopoloQuro@b92c14cb45d399a24de41ad2cb4d89a83abb1cbc Deploy targets: 3; implemented actions: 25; declared actions: 25; uncatalogued served routes: 0; mobile contracts: 1; route signals: 41. ### organizations.data.export Export all Quro data owned by the authenticated organization across D1 and KV storage. Contract: GET /api/organizations/data/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/data/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Permanently erase all Quro data owned by the authenticated organization while retaining backups under policy. Contract: DELETE /api/organizations/data/erase Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.delete Archive an empty Quro workspace via the platform, then drop Quro's local mirror row. Contract: DELETE /api/quro/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/quro/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### qurocodes.list List QURO codes. Contract: GET /qurocodes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "perPage": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "tier": { "type": "string", "enum": [ "all", "basic", "standard", "premium" ] }, "search": { "type": "string", "minLength": 1 }, "statusId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "seriesId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List QURO codes.", "additionalProperties": true } ``` Effects: Reads state through GET /qurocodes without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### qurocodes.create Create QURO codes. Contract: POST /qurocodes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "url": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "tier": { "type": "string", "enum": [ "basic", "standard", "premium" ] }, "status_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "category_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "series_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "name": { "type": "string", "minLength": 1 }, "max_usage": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "valid_from": { "type": "string", "minLength": 1 }, "valid_to": { "type": "string", "minLength": 1 }, "design": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "plain" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "custom" }, "foreground": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false } ] } }, "required": [ "url" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create QURO codes.", "additionalProperties": true } ``` Effects: May change state through POST /qurocodes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### qurocodes.get Get one QURO codes record. Contract: GET /qurocodes/{id_or_slug} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id_or_slug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id_or_slug": { "type": "string", "minLength": 1 } }, "required": [ "id_or_slug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get QURO codes.", "additionalProperties": true } ``` Effects: Reads state through GET /qurocodes/{id_or_slug} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### qurocodes.update Update one QURO codes record. Contract: PUT /qurocodes/{id_or_slug} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id_or_slug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id_or_slug": { "type": "string", "minLength": 1 }, "url": { "type": "string", "minLength": 1 }, "status_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "category_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "series_id": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "name": { "type": "string" }, "max_usage": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, { "type": "null" } ] }, "valid_from": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "valid_to": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "design": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "plain" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "custom" }, "foreground": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false } ] } }, "required": [ "id_or_slug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update QURO codes.", "additionalProperties": true } ``` Effects: May change state through PUT /qurocodes/{id_or_slug}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### qurocodes.delete Delete one QURO codes record. Contract: DELETE /qurocodes/{id_or_slug} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id_or_slug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id_or_slug": { "type": "string", "minLength": 1 } }, "required": [ "id_or_slug" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete QURO codes.", "additionalProperties": true } ``` Effects: May change state through DELETE /qurocodes/{id_or_slug}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### analytics.get Get Quro analytics. Contract: GET /analytics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "quro_id": 1, "slug": "example", "period": "day" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "quro_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "slug": { "type": "string", "minLength": 1 }, "period": { "type": "string", "enum": [ "day", "week", "month", "year" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get analytics.", "additionalProperties": true } ``` Effects: Reads state through GET /analytics without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.assets.list List Quro OpenClaw analytics assets. Contract: GET /openclaw/quro/assets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "perPage": 1, "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100 }, "search": { "type": "string", "minLength": 1 }, "tier": { "type": "string", "enum": [ "all", "basic", "standard", "premium" ] }, "seriesId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "refresh_health": { "type": "string", "enum": [ "true", "false" ] }, "inactivity_days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "window_days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List analytics assets.", "additionalProperties": true } ``` Effects: Reads state through GET /openclaw/quro/assets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.events.list List Quro OpenClaw analytics events. Contract: GET /openclaw/quro/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "from": "example", "to": "example", "slug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "quro_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "event_type": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List analytics events.", "additionalProperties": true } ``` Effects: Reads state through GET /openclaw/quro/events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.rollups.list List Quro OpenClaw analytics rollups. Contract: GET /openclaw/quro/rollups Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "from": "example", "to": "example", "slug": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "quro_id": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List analytics rollups.", "additionalProperties": true } ``` Effects: Reads state through GET /openclaw/quro/rollups without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.summary.get Get Quro OpenClaw analytics summary. Contract: GET /openclaw/quro/summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: analytics:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "inactivity_days": 1, "window_days": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "inactivity_days": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "window_days": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 }, "from": { "type": "string", "minLength": 1 }, "to": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get analytics summary.", "additionalProperties": true } ``` Effects: Reads state through GET /openclaw/quro/summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### metadata.get Get Quro metadata by type. Contract: GET /metadata/{type} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "type": "categories" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "type": { "type": "string", "enum": [ "categories", "statuses", "tiers" ] } }, "required": [ "type" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get metadata.", "additionalProperties": true } ``` Effects: Reads state through GET /metadata/{type} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### series.list List Quro series. Contract: GET /series Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "perPage": 1, "includeArchived": "true" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 100 }, "includeArchived": { "type": "string", "enum": [ "true", "false" ] }, "status": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List series.", "additionalProperties": true } ``` Effects: Reads state through GET /series without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### series.create Create a Quro series. Contract: POST /series Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "description": "example", "status": "active" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "paused", "archived" ] }, "templateId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create series.", "additionalProperties": true } ``` Effects: May change state through POST /series. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### series.templates.list List Quro series templates. Contract: GET /series/templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "category": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List series templates.", "additionalProperties": true } ``` Effects: Reads state through GET /series/templates without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### series.dashboard.get Get one Quro series dashboard. Contract: GET /series/{id}/dashboard Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get series dashboard.", "additionalProperties": true } ``` Effects: Reads state through GET /series/{id}/dashboard without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### series.dashboard.update Update one Quro series dashboard. Contract: PUT /series/{id}/dashboard Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "dashboard": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "resetToDefault": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update series dashboard.", "additionalProperties": true } ``` Effects: May change state through PUT /series/{id}/dashboard. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### series.generate Generate Quro codes for a series. Contract: POST /series/{id}/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "count": { "type": "integer", "minimum": 1, "maximum": 1000 }, "tier": { "type": "string", "enum": [ "basic", "standard", "premium" ] }, "namePattern": { "type": "string", "minLength": 1 }, "urlPattern": { "type": "string", "minLength": 1 }, "categoryId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "statusId": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "startNumber": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "design": { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "plain" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "custom" }, "foreground": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "background": { "type": "string", "pattern": "^#[0-9a-f]{6}$" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "brand" }, "moduleStyle": { "type": "string", "enum": [ "square", "rounded" ] }, "finderStyle": { "type": "string", "enum": [ "square", "rounded", "circle" ] } }, "required": [ "source" ], "additionalProperties": false } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate series.", "additionalProperties": true } ``` Effects: May change state through POST /series/{id}/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### series.generation_templates.list List generation templates for a Quro series. Contract: GET /series/{id}/generation-templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List generation templates.", "additionalProperties": true } ``` Effects: Reads state through GET /series/{id}/generation-templates without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### series.complete Mark a Quro series completed. Contract: POST /series/{id}/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: series:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /series/{id}/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### exports.create Create a durable JSON export of the active workspace's Quro codes. Contract: POST /exports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /exports. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### exports.download Download a ready Quro export artifact. Contract: GET /exports/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: codes:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /exports/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## Topolo Roadmapper source contract Human reference: https://docs.topolo.app/systems/topolo-roadmapper Machine reference: https://docs.topolo.app/machine/systems/topolo-roadmapper.json Source revisions: apps/TopoloRoadmapper@4d949b9e65b36e73fd832edcf0a142205a1db5bd Deploy targets: 2; implemented actions: 74; declared actions: 74; uncatalogued served routes: 0; mobile contracts: 1; route signals: 29. ### organizations.data.export Export all Roadmapper data owned by the authenticated organization across four D1 stores and linked attachment metadata. Contract: GET /api/organizations/data/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/data/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Permanently erase all Roadmapper data owned by the authenticated organization while retaining backups under policy. Contract: DELETE /api/organizations/data/erase Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.list Execute Projects List in Topolo Roadmapper. Contract: GET /api/projects Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.create Call POST /projects. Contract: POST /api/projects Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "on_hold", "completed", "cancelled", "archived" ] } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.update Call PUT /projects/{id}. Contract: PUT /api/projects/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "status": { "type": "string", "enum": [ "active", "on_hold", "completed", "cancelled", "archived" ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/projects/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.delete Call DELETE /projects/{id}. Contract: DELETE /api/projects/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/projects/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.archive Call POST /projects/{id}/archive. Contract: POST /api/projects/{id}/archive Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "archive": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "archive": { "type": "boolean" } }, "required": [ "id", "archive" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Archive.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/{id}/archive. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.guest_shares.create Execute Projects Guest Shares Create in Topolo Roadmapper. Contract: POST /api/projects/{id}/share-guest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expiresInHours": { "anyOf": [ { "type": "number", "minimum": 1, "maximum": 720 }, { "type": "null" } ] }, "accessMode": { "type": "string", "enum": [ "view", "edit" ] }, "allowItemNavigation": { "type": "boolean" }, "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/{id}/share-guest. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.guest_shares.list Execute Projects Guest Shares List in Topolo Roadmapper. Contract: GET /api/projects/{id}/share-guest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/{id}/share-guest without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.guest_shares.revoke Execute Projects Guest Shares Revoke in Topolo Roadmapper. Contract: DELETE /api/projects/{id}/share-guest/{token} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "token": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "id", "token" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/projects/{id}/share-guest/{token}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.guest_shares.invite Execute Projects Guest Shares Invite in Topolo Roadmapper. Contract: POST /api/projects/{id}/share-guest/{token}/invite-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "recipientEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "id", "token", "recipientEmail" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/{id}/share-guest/{token}/invite-email. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.presentations.generate Call POST /projects/{id}/presentations/generate. Contract: POST /api/projects/{id}/presentations/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "template": { "type": "string", "enum": [ "executive_status_update", "steering_committee_review", "program_increment_review", "customer_safe_roadmap_update", "delivery_risk_review" ] }, "scenarioId": { "type": "string" }, "liveLinked": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Presentations Generate.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/{id}/presentations/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.planning_sessions.create Call POST /projects/{id}/planning/sessions. Contract: POST /api/projects/{id}/planning/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 120 }, "scopeType": { "type": "string", "enum": [ "project", "roadmap", "item" ] }, "scopeRecordId": { "type": "string", "minLength": 1, "maxLength": 128 }, "impactMode": { "type": "string", "enum": [ "project_wide", "selected_only", "selected_with_descendants" ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Planning Sessions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/{id}/planning/sessions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.ai_draft.create Call POST /projects/ai/draft. Contract: POST /api/projects/ai/draft Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "messages": [ { "role": "user", "content": "example" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "messages": { "minItems": 1, "maxItems": 40, "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "user", "assistant" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "role", "content" ], "additionalProperties": false } }, "currentDraft": { "anyOf": [ { "type": "object", "properties": { "project": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "roadmaps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": "string", "maxLength": 255 }, "children": { "type": "array", "items": {} } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name", "items" ], "additionalProperties": false } } }, "required": [ "project", "roadmaps" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "messages" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Draft Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/ai/draft. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.ai_apply Call POST /projects/ai/apply. Contract: POST /api/projects/ai/apply Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "draft": { "project": { "name": "example" }, "roadmaps": [ { "name": "example", "items": [ { "name": "example" } ] } ] } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "draft": { "type": "object", "properties": { "project": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "roadmaps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": "string", "maxLength": 255 }, "children": { "type": "array", "items": {} } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name", "items" ], "additionalProperties": false } } }, "required": [ "project", "roadmaps" ], "additionalProperties": false } }, "required": [ "draft" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Apply.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/ai/apply. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.ai_sessions.create Call POST /projects/ai/sessions. Contract: POST /api/projects/ai/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Sessions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/ai/sessions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.ai_sessions.update Call PATCH /projects/ai/sessions/{id}. Contract: PATCH /api/projects/ai/sessions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "draft": { "project": { "name": "example" }, "roadmaps": [ { "name": "example", "items": [] } ] } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "draft": { "anyOf": [ { "type": "object", "properties": { "project": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name" ], "additionalProperties": false }, "roadmaps": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "assignee": { "type": "string", "maxLength": 255 }, "children": { "type": "array", "items": {} } }, "required": [ "name" ], "additionalProperties": false } } }, "required": [ "name", "items" ], "additionalProperties": false } } }, "required": [ "project", "roadmaps" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "draft" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Sessions Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/projects/ai/sessions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.ai_sessions.delete Call DELETE /projects/ai/sessions/{id}. Contract: DELETE /api/projects/ai/sessions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Sessions Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/projects/ai/sessions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.ai_sessions.turns.create Call POST /projects/ai/sessions/{id}/turns. Contract: POST /api/projects/ai/sessions/{id}/turns Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "message": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 } }, "required": [ "id", "message" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Sessions Turns Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/ai/sessions/{id}/turns. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### projects.ai_sessions.apply Call POST /projects/ai/sessions/{id}/apply. Contract: POST /api/projects/ai/sessions/{id}/apply Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Sessions Apply.", "additionalProperties": true } ``` Effects: May change state through POST /api/projects/ai/sessions/{id}/apply. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.create Call POST /items. Contract: POST /api/items Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "roadmapId": "example", "name": "example", "status": "planned", "priority": "low" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "assigneeUserId": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "roadmapId", "name", "status", "priority" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Items Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/items. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.update Call PATCH /items/{id}. Contract: PATCH /api/items/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "assigneeUserId": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Items Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/items/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.delete Call DELETE /items/{id}. Contract: DELETE /api/items/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Items Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/items/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.presentations.generate Call POST /items/{id}/presentations/generate. Contract: POST /api/items/{id}/presentations/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "template": { "type": "string", "enum": [ "executive_status_update", "steering_committee_review", "program_increment_review", "customer_safe_roadmap_update", "delivery_risk_review" ] }, "scenarioId": { "type": "string" }, "liveLinked": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Items Presentations Generate.", "additionalProperties": true } ``` Effects: May change state through POST /api/items/{id}/presentations/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.guest_shares.create Execute Items Guest Shares Create in Topolo Roadmapper. Contract: POST /api/items/{id}/share-guest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expiresInHours": { "anyOf": [ { "type": "number", "minimum": 1, "maximum": 720 }, { "type": "null" } ] }, "accessMode": { "type": "string", "enum": [ "view", "edit" ] }, "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/items/{id}/share-guest. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.guest_shares.list Execute Items Guest Shares List in Topolo Roadmapper. Contract: GET /api/items/{id}/share-guest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/items/{id}/share-guest without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### items.guest_shares.revoke Execute Items Guest Shares Revoke in Topolo Roadmapper. Contract: DELETE /api/items/{id}/share-guest/{token} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "token": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "id", "token" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/items/{id}/share-guest/{token}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.guest_shares.invite Execute Items Guest Shares Invite in Topolo Roadmapper. Contract: POST /api/items/{id}/share-guest/{token}/invite-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "recipientEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "id", "token", "recipientEmail" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/items/{id}/share-guest/{token}/invite-email. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.guest_scope.create Execute Items Guest Scope Create in Topolo Roadmapper. Contract: POST /api/items/guest/{scope}/items Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "scope": "example", "roadmapId": "example", "name": "example", "status": "planned", "priority": "low" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1 }, "roadmapId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "scope", "roadmapId", "name", "status", "priority" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/items/guest/{scope}/items. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### items.guest_scope.update Execute Items Guest Scope Update in Topolo Roadmapper. Contract: PATCH /api/items/guest/{scope}/items/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "scope": "example", "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "description": { "type": "string", "maxLength": 1000 }, "status": { "type": "string", "enum": [ "planned", "in_progress", "completed", "blocked" ] }, "priority": { "type": "string", "enum": [ "low", "medium", "high", "critical" ] }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "assignee": { "type": "string", "maxLength": 255 }, "parentItemId": { "type": "string" } }, "required": [ "scope", "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/items/guest/{scope}/items/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### roadmaps.list Execute Roadmaps List in Topolo Roadmapper. Contract: GET /api/roadmaps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/roadmaps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### roadmaps.create Call POST /roadmaps. Contract: POST /api/roadmaps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "projectId": "example", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "projectId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Roadmaps Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/roadmaps. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### roadmaps.update Call PUT /roadmaps/{id}. Contract: PUT /api/roadmaps/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "projectId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "status": { "type": "string", "enum": [ "active", "completed", "archived" ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Roadmaps Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/roadmaps/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### roadmaps.delete Call DELETE /roadmaps/{id}. Contract: DELETE /api/roadmaps/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Roadmaps Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/roadmaps/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### roadmaps.presentations.generate Call POST /roadmaps/{id}/presentations/generate. Contract: POST /api/roadmaps/{id}/presentations/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "template": { "type": "string", "enum": [ "executive_status_update", "steering_committee_review", "program_increment_review", "customer_safe_roadmap_update", "delivery_risk_review" ] }, "scenarioId": { "type": "string" }, "liveLinked": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Roadmaps Presentations Generate.", "additionalProperties": true } ``` Effects: May change state through POST /api/roadmaps/{id}/presentations/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### roadmaps.guest_shares.create Execute Roadmaps Guest Shares Create in Topolo Roadmapper. Contract: POST /api/roadmaps/{id}/share-guest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "expiresInHours": { "anyOf": [ { "type": "number", "minimum": 1, "maximum": 720 }, { "type": "null" } ] }, "accessMode": { "type": "string", "enum": [ "view", "edit" ] }, "allowItemNavigation": { "type": "boolean" }, "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/roadmaps/{id}/share-guest. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### roadmaps.guest_shares.list Execute Roadmaps Guest Shares List in Topolo Roadmapper. Contract: GET /api/roadmaps/{id}/share-guest Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/roadmaps/{id}/share-guest without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### roadmaps.guest_shares.revoke Execute Roadmaps Guest Shares Revoke in Topolo Roadmapper. Contract: DELETE /api/roadmaps/{id}/share-guest/{token} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "token": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "id", "token" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/roadmaps/{id}/share-guest/{token}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### roadmaps.guest_shares.invite Execute Roadmaps Guest Shares Invite in Topolo Roadmapper. Contract: POST /api/roadmaps/{id}/share-guest/{token}/invite-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "token": "example", "recipientEmail": "user@example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 }, "recipientEmail": { "type": "string", "format": "email", "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" } }, "required": [ "id", "token", "recipientEmail" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/roadmaps/{id}/share-guest/{token}/invite-email. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### dependencies.create Call POST /dependencies. Contract: POST /api/dependencies Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "fromItemId": "example", "toItemId": "example", "type": "blocks" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "fromItemId": { "type": "string", "minLength": 1 }, "toItemId": { "type": "string", "minLength": 1 }, "type": { "type": "string", "enum": [ "blocks", "requires", "related" ] } }, "required": [ "fromItemId", "toItemId", "type" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Dependencies Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/dependencies. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### dependencies.delete Call DELETE /dependencies/{id}. Contract: DELETE /api/dependencies/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Dependencies Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/dependencies/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### comments.create Call POST /comments. Contract: POST /api/comments Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "roadmapItemId": "example", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 }, "mentionedUserIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 50 } }, "required": [ "roadmapItemId", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Comments Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/comments. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### comments.update Call PUT /comments/{commentId}. Contract: PUT /api/comments/{commentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "commentId": "example", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "commentId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "commentId", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Comments Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/comments/{commentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### comments.delete Call DELETE /comments/{commentId}. Contract: DELETE /api/comments/{commentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "commentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "commentId": { "type": "string", "minLength": 1 } }, "required": [ "commentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Comments Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/comments/{commentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### attachments.upload Call POST /attachments/upload. Contract: POST /api/attachments/upload Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "roadmapItemId": "example", "fileName": "example", "contentType": "example", "base64": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 }, "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "base64": { "type": "string", "minLength": 1, "maxLength": 14000000 } }, "required": [ "roadmapItemId", "fileName", "contentType", "base64" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Attachments Upload.", "additionalProperties": true } ``` Effects: May change state through POST /api/attachments/upload. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### attachments.delete Call DELETE /attachments/{attachmentId}. Contract: DELETE /api/attachments/{attachmentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "attachmentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attachmentId": { "type": "string", "minLength": 1 } }, "required": [ "attachmentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Attachments Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/attachments/{attachmentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### reports.generate Call POST /reports/generate. Contract: POST /api/reports/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "filters": { "projectIds": [ "example" ], "roadmapIds": [ "example" ], "statuses": [ "example" ] } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "description": { "type": "string" }, "filters": { "type": "object", "properties": { "projectIds": { "type": "array", "items": { "type": "string" } }, "roadmapIds": { "type": "array", "items": { "type": "string" } }, "statuses": { "type": "array", "items": { "type": "string" } }, "priorities": { "type": "array", "items": { "type": "string" } }, "dateRange": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "assignees": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "required": [ "title", "filters" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reports Generate.", "additionalProperties": true } ``` Effects: May change state through POST /api/reports/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### imports.csv Execute Imports Csv in Topolo Roadmapper. Contract: POST /api/import Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "csv": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "csv": { "type": "string", "minLength": 1 }, "importType": { "type": "string", "enum": [ "roadmaps", "projects", "combined" ] } }, "required": [ "csv" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/import. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### planning.sessions.delete Call DELETE /planning/sessions/{id}. Contract: DELETE /api/planning/sessions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Planning Sessions Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/planning/sessions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### planning.turns.create Call POST /planning/sessions/{id}/turns. Contract: POST /api/planning/sessions/{id}/turns Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "message": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1, "maxLength": 4000 }, "document": {} }, "required": [ "id", "message" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Planning Turns Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/planning/sessions/{id}/turns. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### planning.scenarios.create Call POST /planning/sessions/{id}/scenarios. Contract: POST /api/planning/sessions/{id}/scenarios Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "document": {} }, "required": [ "id", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Planning Scenarios Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/planning/sessions/{id}/scenarios. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### planning.apply Call POST /planning/sessions/{id}/apply. Contract: POST /api/planning/sessions/{id}/apply Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "document": {} }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Planning Apply.", "additionalProperties": true } ``` Effects: May change state through POST /api/planning/sessions/{id}/apply. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### presentations.update Call PATCH /presentations/{id}. Contract: PATCH /api/presentations/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "summary": { "type": "string", "maxLength": 1200 }, "slides": { "type": "array", "items": {} } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Presentations Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/presentations/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### presentations.export Call POST /presentations/{id}/export. Contract: POST /api/presentations/{id}/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "format": "web" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "format": { "type": "string", "enum": [ "web", "pptx" ] } }, "required": [ "id", "format" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Presentations Export.", "additionalProperties": true } ``` Effects: May change state through POST /api/presentations/{id}/export. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Archive an empty Roadmapper workspace: Roadmapper confirms it holds no planning data, then asks the platform to archive it. Contract: DELETE /api/roadmapper/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/roadmapper/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.get Call GET /projects/{id}. Contract: GET /api/projects/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.dashboard.get Call GET /projects/{id}/dashboard. Contract: GET /api/projects/{id}/dashboard Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Dashboard Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/{id}/dashboard without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.planning_feed.get Call GET /projects/{id}/planning-feed. Contract: GET /api/projects/{id}/planning-feed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: projects:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Planning Feed Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/{id}/planning-feed without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.planning_sessions.list Call GET /projects/{id}/planning/sessions. Contract: GET /api/projects/{id}/planning/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Planning Sessions List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/{id}/planning/sessions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.ai_status.get Call GET /projects/ai/status. Contract: GET /api/projects/ai/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Status Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/ai/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.ai_sessions.list Call GET /projects/ai/sessions. Contract: GET /api/projects/ai/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Sessions List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/ai/sessions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### projects.ai_sessions.get Call GET /projects/ai/sessions/{id}. Contract: GET /api/projects/ai/sessions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Projects Ai Sessions Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/projects/ai/sessions/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### items.get Call GET /items/{id}. Contract: GET /api/items/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Items Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/items/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### roadmaps.get Call GET /roadmaps/{id}. Contract: GET /api/roadmaps/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Roadmaps Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/roadmaps/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### roadmaps.items.list Call GET /roadmaps/{id}/items. Contract: GET /api/roadmaps/{id}/items Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Roadmaps Items List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/roadmaps/{id}/items without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### dependencies.item.list Call GET /dependencies/item/{id}. Contract: GET /api/dependencies/item/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Dependencies Item List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/dependencies/item/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### comments.by_roadmap_item.list Call GET /comments/roadmap-item/{roadmapItemId}. Contract: GET /api/comments/roadmap-item/{roadmapItemId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "roadmapItemId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 } }, "required": [ "roadmapItemId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Comments By Roadmap Item List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/comments/roadmap-item/{roadmapItemId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### attachments.by_roadmap_item.list Call GET /attachments/roadmap-item/{roadmapItemId}. Contract: GET /api/attachments/roadmap-item/{roadmapItemId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "roadmapItemId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapItemId": { "type": "string", "minLength": 1 }, "includeDescendants": { "type": "string", "enum": [ "true", "false" ] } }, "required": [ "roadmapItemId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Attachments By Roadmap Item List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/attachments/roadmap-item/{roadmapItemId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### attachments.by_roadmap.list Call GET /attachments/roadmap/{roadmapId}. Contract: GET /api/attachments/roadmap/{roadmapId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "roadmapId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "roadmapId": { "type": "string", "minLength": 1 } }, "required": [ "roadmapId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Attachments By Roadmap List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/attachments/roadmap/{roadmapId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### attachments.download Call GET /attachments/{attachmentId}/download. Contract: GET /api/attachments/{attachmentId}/download Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "attachmentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "attachmentId": { "type": "string", "minLength": 1 } }, "required": [ "attachmentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Attachments Download.", "additionalProperties": true } ``` Effects: Reads state through GET /api/attachments/{attachmentId}/download without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### planning.sessions.get Call GET /planning/sessions/{id}. Contract: GET /api/planning/sessions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Planning Sessions Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/planning/sessions/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### planning.revisions.list Call GET /planning/sessions/{id}/revisions. Contract: GET /api/planning/sessions/{id}/revisions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: roadmaps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Planning Revisions List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/planning/sessions/{id}/revisions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### presentations.get Call GET /presentations/{id}. Contract: GET /api/presentations/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Presentations Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/presentations/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## Topolo Status source contract Human reference: https://docs.topolo.app/systems/topolo-status Machine reference: https://docs.topolo.app/machine/systems/topolo-status.json Source revisions: system-apps/TopoloStatus@7c200769ec189bf8efe4fe3c0030a7e72627ad81 Deploy targets: 1; implemented actions: 7; declared actions: 9; uncatalogued served routes: 0; mobile contracts: 1; route signals: 9. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: status:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### status.get Get platform status. Contract: GET /api/status Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get status.", "additionalProperties": true } ``` Effects: Reads state through GET /api/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### status.poll Poll all configured platform surfaces immediately. Contract: POST /poll Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: status:poll Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Poll status.", "additionalProperties": true } ``` Effects: May change state through POST /poll. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### incidents.create Create a durable platform status incident. Contract: POST /api/incidents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: status:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "message": "example", "severity": "minor" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "enum": [ "minor", "major", "critical" ] }, "componentHost": { "type": "string", "minLength": 1 }, "componentName": { "type": "string", "minLength": 1 } }, "required": [ "title", "message", "severity" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/incidents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### incidents.update Publish a durable update to an open status incident. Contract: PATCH /api/incidents/{incidentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: status:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "incidentId": "example", "message": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "incidentId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "severity": { "type": "string", "enum": [ "minor", "major", "critical" ] }, "status": { "type": "string", "enum": [ "investigating", "identified", "monitoring" ] } }, "required": [ "incidentId", "message" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/incidents/{incidentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### incidents.resolve Resolve an open status incident with a final update. Contract: POST /api/incidents/{incidentId}/resolve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: status:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "incidentId": "example", "message": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "incidentId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "incidentId", "message" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/incidents/{incidentId}/resolve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### maintenance.schedule Create a durable scheduled maintenance window. Contract: POST /api/maintenance Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: status:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "message": "example", "scheduledStart": "example", "scheduledEnd": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 }, "scheduledStart": { "type": "string", "minLength": 1 }, "scheduledEnd": { "type": "string", "minLength": 1 } }, "required": [ "title", "message", "scheduledStart", "scheduledEnd" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/maintenance. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### maintenance.start Move a scheduled maintenance window into progress. Contract: POST /api/maintenance/{maintenanceId}/start Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: status:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "maintenanceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "maintenanceId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "maintenanceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/maintenance/{maintenanceId}/start. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### maintenance.complete Complete an in-progress maintenance window. Contract: POST /api/maintenance/{maintenanceId}/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: status:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "maintenanceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "maintenanceId": { "type": "string", "minLength": 1 }, "message": { "type": "string", "minLength": 1 } }, "required": [ "maintenanceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/maintenance/{maintenanceId}/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## Topolo Support source contract Human reference: https://docs.topolo.app/systems/topolo-support Machine reference: https://docs.topolo.app/machine/systems/topolo-support.json Source revisions: apps/TopoloSupport@77105cf20c40ad714d45907641b33ea6a6dbdd04 Deploy targets: 2; implemented actions: 25; declared actions: 26; uncatalogued served routes: 0; mobile contracts: 1; route signals: 7. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: tickets:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.delete Delete an empty non-default support workspace. Contract: DELETE /api/support/workspace/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/support/workspace/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### inboxes.create Create an inbox in a support workspace. Contract: POST /api/support/workspace/{workspaceId}/inboxes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "name": "example" } ``` Input schema: ```json { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 2 }, "slug": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "portal", "api", "email", "webhook", "widget", "messaging", "manual" ] }, "isDefault": { "type": "boolean" } }, "required": [ "workspaceId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/support/workspace/{workspaceId}/inboxes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### inboxes.update Update an inbox in a support workspace. Contract: PATCH /api/support/workspace/{workspaceId}/inboxes/{inboxId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "inboxId": "example" } ``` Input schema: ```json { "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "inboxId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 2 }, "slug": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "enum": [ "portal", "api", "email", "webhook", "widget", "messaging", "manual" ] }, "isDefault": { "type": "boolean" }, "isActive": { "type": "boolean" } }, "required": [ "workspaceId", "inboxId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/support/workspace/{workspaceId}/inboxes/{inboxId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tickets.list List support tickets. Contract: GET /api/support/tickets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List tickets.", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/tickets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### tickets.create Create a support ticket. Contract: POST /api/support/tickets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "inboxId": "example", "subject": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "inboxId": { "type": "string", "minLength": 1 }, "subject": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "serviceName": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "priority": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "requesterName": { "type": "string", "minLength": 1 }, "requesterEmail": { "type": "string", "minLength": 1 }, "requesterUserId": { "type": "string", "minLength": 1 }, "requesterOrgId": { "type": "string", "minLength": 1 }, "source": { "type": "string", "minLength": 1 }, "sourceReference": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create ticket.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/tickets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tickets.get Get one support ticket. Contract: GET /api/support/tickets/{ticketId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "ticketId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get ticket.", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/tickets/{ticketId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### tickets.update Update one support ticket. Contract: PATCH /api/support/tickets/{ticketId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "ticketId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "priority": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "assignedToUserId": { "type": "string", "minLength": 1 }, "assignedToName": { "type": "string", "minLength": 1 }, "assignedToEmail": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update ticket.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/support/tickets/{ticketId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ticket_messages.create Add a message to a support ticket. Contract: POST /api/support/tickets/{ticketId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "ticketId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "visibility": { "type": "string", "minLength": 1 }, "channel": { "type": "string", "minLength": 1 }, "sourceReference": { "type": "string", "minLength": 1 }, "macroId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create ticket message.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/tickets/{ticketId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### macros.list List support macros. Contract: GET /api/support/macros Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: macros:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List macros.", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/macros without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### macros.get Get one support macro. Contract: GET /api/support/macros/{macroId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: macros:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "macroId": "example" } ``` Input schema: ```json { "type": "object", "properties": { "macroId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "macroId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/macros/{macroId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### macros.create Create a support macro. Contract: POST /api/support/macros Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: macros:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "title": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "visibility": { "type": "string", "minLength": 1 }, "suggestedStatus": { "type": "string", "minLength": 1 }, "suggestedPriority": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create macro.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/macros. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.get Get support routing, triage, agent capacity, and queue analytics. Contract: GET /api/support/operations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get operations overview.", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/operations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### operations.section.get Get one support operations section. Contract: GET /api/support/operations/{section} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "section": "overview" } ``` Input schema: ```json { "type": "object", "properties": { "section": { "type": "string", "enum": [ "overview", "workspaces", "settings", "agents", "routing", "channels", "intelligence" ] }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "section" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/operations/{section} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### operations.settings.update Update support workspace assignment, triage, CSAT, timezone, and business-hour settings. Contract: PATCH /api/support/operations/settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "timezone": "example", "businessHours": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "timezone": { "type": "string", "minLength": 1 }, "businessHours": { "type": "string" }, "autoAssignmentEnabled": { "type": "boolean" }, "aiTriageEnabled": { "type": "boolean" }, "csatEnabled": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update operations settings.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/support/operations/settings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.agents.update Update a support agent status, capacity, skills, or active state. Contract: PATCH /api/support/operations/agents/{agentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "agentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "agentId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "maxCapacity": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "skills": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "isActive": { "type": "boolean" } }, "required": [ "agentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update support agent profile.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/support/operations/agents/{agentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.routing_rules.create Create a support routing rule for ticket assignment. Contract: POST /api/support/operations/routing-rules Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example", "name": "example", "priorityOrder": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "priorityOrder": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "matchSource": { "type": "string" }, "matchCategory": { "type": "string" }, "matchPriority": { "type": "string" }, "targetInboxId": { "type": "string" }, "requiredSkills": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "isActive": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create routing rule.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/operations/routing-rules. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.routing_rules.update Update a support routing rule for ticket assignment. Contract: PATCH /api/support/operations/routing-rules/{ruleId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "ruleId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ruleId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "priorityOrder": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "matchSource": { "type": "string" }, "matchCategory": { "type": "string" }, "matchPriority": { "type": "string" }, "targetInboxId": { "type": "string" }, "requiredSkills": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "isActive": { "type": "boolean" } }, "required": [ "ruleId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update routing rule.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/support/operations/routing-rules/{ruleId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.channel_connections.create Connect an IMAP mailbox to a support inbox through Nexus-managed mailbox credentials. Contract: POST /api/support/operations/channel-connections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "inboxId": "example", "authUsername": "example", "authPassword": "example", "imapHost": "example", "smtpHost": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "inboxId": { "type": "string", "minLength": 1 }, "provider": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "authUsername": { "type": "string", "minLength": 1 }, "authPassword": { "type": "string", "minLength": 1 }, "imapHost": { "type": "string", "minLength": 1 }, "imapPort": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "imapSecure": { "type": "boolean" }, "smtpHost": { "type": "string", "minLength": 1 }, "smtpPort": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "smtpSecure": { "type": "boolean" } }, "required": [ "inboxId", "authUsername", "authPassword", "imapHost", "smtpHost" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Connect support mailbox channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/operations/channel-connections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.channel_connections.sync Fetch new IMAP messages from a connected support mailbox channel. Contract: POST /api/support/operations/channel-connections/{connectionId}/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "connectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 }, "workspaceId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "connectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sync support mailbox channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/operations/channel-connections/{connectionId}/sync. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.triage Refresh deterministic triage summaries, intents, sentiment, and automation scores for open tickets. Contract: POST /api/support/operations/triage Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Refresh triage intelligence.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/operations/triage. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.route Assign open support tickets to active agents using workspace routing rules and capacity. Contract: POST /api/support/operations/route Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tickets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Run routing assignment.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/operations/route. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ticket_notifications.dispatch Dispatch notifications for a support ticket. Contract: POST /api/support/tickets/{ticketId}/notifications/dispatch Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: replies:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "ticketId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Dispatch ticket notification.", "additionalProperties": true } ``` Effects: May change state through POST /api/support/tickets/{ticketId}/notifications/dispatch. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### privacy.export Export the authenticated organization's portable Support data with secrets and operational errors redacted. Contract: GET /api/support/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/privacy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.erase Permanently erase the authenticated organization's Support data and retain only a hash-based erasure receipt. Contract: DELETE /api/support/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/support/privacy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### privacy.protection_canary Verify ticket content, requester and assignee PII, message and notification bodies, webhook payloads, and sensitive source references use readable canonical protection envelopes with valid keyed lookup digests. Contract: GET /api/support/privacy/protection/canary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/support/privacy/protection/canary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## TopoloCommerce source contract Human reference: https://docs.topolo.app/systems/topolo-commerce Machine reference: https://docs.topolo.app/machine/systems/topolo-commerce.json Source revisions: apps/TopoloCommerce@76e2638beb52f038bbe3095e1a3b2e8fb83ce886 Deploy targets: 4; implemented actions: 66; declared actions: 66; uncatalogued served routes: 0; mobile contracts: 1; route signals: 127. ### organizations.data.export Export organization-authored Commerce data and object metadata without credentials or binary payloads. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase organization-authored Commerce data, object storage, and live queue projections after literal ERASE confirmation. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "example", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Delete an empty non-default Commerce workspace. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### org.context.get Get commerce organization context. Contract: GET /api/org/context Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get commerce context.", "additionalProperties": true } ``` Effects: Reads state through GET /api/org/context without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.list List commerce venues. Contract: GET /api/venues Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List venues.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.create Create a commerce venue. Contract: POST /api/venues Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "clientMutationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "slug": { "type": "string" }, "presetKey": { "type": "string" }, "verticalPack": { "type": "string" }, "serviceModel": { "type": "string" }, "paymentMode": { "type": "string" }, "summary": { "type": "string" }, "experience": { "type": "object", "properties": {}, "additionalProperties": {} }, "moduleOverrides": { "type": "object", "properties": {}, "additionalProperties": {} }, "catalogSeed": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "name", "clientMutationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create venue.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.get Get one commerce venue. Contract: GET /api/venues/{venueId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get venue.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.update Update a Commerce venue. Contract: PUT /api/venues/{venueId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "presetKey": { "type": "string" }, "moduleSettings": { "type": "object", "properties": {}, "additionalProperties": {} }, "enabledModules": { "type": "array", "items": { "type": "string" } }, "disabledModules": { "type": "array", "items": { "type": "string" } }, "moduleOverrides": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update venue.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### devices.list List devices for a venue. Contract: GET /api/venues/{venueId}/devices Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List venue devices.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/devices without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### orders.list List commerce orders. Contract: GET /api/orders Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: queues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List orders.", "additionalProperties": true } ``` Effects: Reads state through GET /api/orders without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### orders.create Create a commerce order. Contract: POST /api/orders Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "lines": [ { "itemId": "example" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "lines": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "notes": { "type": "string" }, "selectedModifiers": { "type": "array", "items": { "type": "object", "properties": { "groupId": { "type": "string", "minLength": 1 }, "optionIds": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "groupId" ], "additionalProperties": false } } }, "required": [ "itemId" ], "additionalProperties": false } }, "guestSessionId": { "type": "string" }, "tableTabMemberId": { "type": "string" }, "deviceToken": { "type": "string" }, "tableLabel": { "type": "string" }, "zoneLabel": { "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "draftOrderId": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "lines" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create order.", "additionalProperties": true } ``` Effects: May change state through POST /api/orders. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### service_requests.list List commerce service requests. Contract: GET /api/service-requests Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example", "guestSessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "guestSessionId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "guestSessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List service requests.", "additionalProperties": true } ``` Effects: Reads state through GET /api/service-requests without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### service_requests.update Update one service request. Contract: PATCH /api/service-requests/{requestId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "requestId": "example", "guestSessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "guestSessionId": { "type": "string", "minLength": 1 }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "requestId", "guestSessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update service request.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/service-requests/{requestId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### payment_sessions.create Create a commerce payment session. Contract: POST /api/payment-sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: payments:create Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "orderId": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create payment session.", "additionalProperties": true } ``` Effects: May change state through POST /api/payment-sessions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### publishing.push Push venue edge/runtime state. Contract: POST /api/venues/{venueId}/edge/push Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "events": [ {} ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "events": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "runtimeState": { "type": "object", "properties": {}, "additionalProperties": {} } }, "required": [ "venueId", "events" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Push venue edge update.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/edge/push. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### org.module_settings.get Get Commerce organization module settings. Contract: GET /api/org/module-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get module settings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/org/module-settings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### org.module_settings.update Update Commerce organization module settings. Contract: PUT /api/org/module-settings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "presetKey": "example", "moduleSettings": {}, "enabledModules": [ "example" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presetKey": { "type": "string" }, "moduleSettings": { "type": "object", "properties": {}, "additionalProperties": {} }, "enabledModules": { "type": "array", "items": { "type": "string" } }, "disabledModules": { "type": "array", "items": { "type": "string" } }, "moduleOverrides": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update module settings.", "additionalProperties": true } ``` Effects: May change state through PUT /api/org/module-settings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### org.module_settings.resolve Resolve Commerce module settings. Contract: POST /api/org/module-settings/resolve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "presetKey": "example", "orgSettings": {}, "venueOverrides": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "presetKey": { "type": "string" }, "orgSettings": { "type": "object", "properties": {}, "additionalProperties": {} }, "venueOverrides": { "type": "object", "properties": {}, "additionalProperties": {} } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Resolve module settings.", "additionalProperties": true } ``` Effects: May change state through POST /api/org/module-settings/resolve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### org.hub_tiles.update Update Commerce organization hub tiles. Contract: PUT /api/org/hub-tiles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "tiles": [ {} ], "clientMutationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "tiles": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update hub tiles.", "additionalProperties": true } ``` Effects: May change state through PUT /api/org/hub-tiles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.experience.get Get Commerce venue experience settings. Contract: GET /api/venues/{venueId}/experience Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get venue experience.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/experience without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.experience.update Update Commerce venue experience settings. Contract: PUT /api/venues/{venueId}/experience Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "presentationMode": { "type": "string" }, "fontPreset": { "type": "string" }, "menuCardStyle": { "type": "string" }, "serviceActionStyle": { "type": "string" }, "accentColor": { "type": "string" }, "currency": { "type": "string" }, "locale": { "type": "string" }, "brandSurface": { "type": "string" }, "logoUrl": { "type": "string" }, "orderIntentTimer": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update venue experience.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/experience. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.hub_tiles.update Update Commerce venue hub tiles. Contract: PUT /api/venues/{venueId}/hub-tiles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "tiles": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update venue hub tiles.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/hub-tiles. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.catalog.get Get a Commerce venue catalog. Contract: GET /api/venues/{venueId}/catalog Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get venue catalog.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/catalog without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.catalog.update Update a Commerce venue catalog. Contract: PUT /api/venues/{venueId}/catalog Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: catalog:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "kind": { "type": "string" }, "sections": { "type": "array", "items": { "type": "object", "properties": {}, "additionalProperties": {} } }, "serviceActions": { "type": "array", "items": { "type": "string" } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update venue catalog.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/catalog. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.beverage_guide.get Get Commerce venue beverage guide. Contract: GET /api/venues/{venueId}/beverage-guide Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get beverage guide.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/beverage-guide without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.resilience_state.get Get Commerce venue resilience state. Contract: GET /api/venues/{venueId}/resilience/state Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get resilience state.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/resilience/state without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.devices.link Link a Commerce venue device. Contract: POST /api/venues/{venueId}/devices/link Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "mdmDeviceId": { "type": "string" }, "deviceId": { "type": "string" }, "commerceDeviceId": { "type": "string" }, "mdmLabel": { "type": "string" }, "label": { "type": "string" }, "roleKey": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "assignmentMode": { "type": "string" }, "assignedStaffId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "deviceType": { "type": "string" }, "authPolicy": { "type": "string" }, "localIdentifier": { "type": "string" }, "mdmLastSeenAt": { "type": "number" }, "mdmManufacturer": { "type": "string" }, "mdmModel": { "type": "string" }, "mdmSerialNumber": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Link venue device.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/devices/link. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.devices.profile.update Update a Commerce venue device profile. Contract: PUT /api/venues/{venueId}/devices/{deviceId}/profile Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 }, "profile": { "type": "object", "properties": {}, "additionalProperties": {} }, "mode": { "type": "string" }, "kioskState": { "type": "string" }, "policyPreset": { "type": "string" }, "launcherPackage": { "type": "string" }, "launcherTarget": { "type": "object", "properties": {}, "additionalProperties": {} }, "contentAssignment": { "type": "object", "properties": {}, "additionalProperties": {} }, "metadata": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update venue device profile.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/devices/{deviceId}/profile. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.devices.command.create Create a Commerce venue device command. Contract: POST /api/venues/{venueId}/devices/{deviceId}/command Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "deviceId": "example", "action": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 }, "action": { "type": "string", "minLength": 1 }, "commandId": { "type": "string" }, "parameters": { "type": "object", "properties": {}, "additionalProperties": {} }, "packageName": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "deviceId", "action" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create venue device command.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/devices/{deviceId}/command. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.payment_reconciliations.list List Commerce venue payment reconciliations. Contract: GET /api/venues/{venueId}/payment-reconciliations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List payment reconciliations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/payment-reconciliations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.payment_reconciliations.create Create a Commerce venue payment reconciliation. Contract: POST /api/venues/{venueId}/payment-reconciliations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: payments:create Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "orderId": "example", "settlementKind": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "orderId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "settlementKind": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "amountCents": { "type": "number" }, "externalReference": { "type": "string" }, "note": { "type": "string" }, "source": { "type": "string" }, "recordedAt": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "orderId", "settlementKind" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create payment reconciliation.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/payment-reconciliations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.sync_policy.get Get Commerce venue sync policy. Contract: GET /api/venues/{venueId}/sync-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get sync policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/sync-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.sync_policy.update Update Commerce venue sync policy. Contract: PUT /api/venues/{venueId}/sync-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "preferredSyncMode": { "type": "string" }, "rescueUplinkEnabled": { "type": "boolean" }, "rescueActivationAfterSeconds": { "type": "number" }, "unsyncedEventThreshold": { "type": "number" }, "maxRescueSessionMinutes": { "type": "number" }, "minPrimaryHealthySeconds": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update sync policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/sync-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.staff_notifications.list List Commerce venue staff notifications. Contract: GET /api/venues/{venueId}/staff-notifications Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "staffMemberId": { "type": "string" }, "status": { "type": "string" } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List staff notifications.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/staff-notifications without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.staff_notifications.update Update a Commerce staff notification. Contract: PUT /api/venues/{venueId}/staff-notifications/{notificationId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: queues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "notificationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "notificationId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "accepted", "dismissed" ] }, "acceptedAt": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "notificationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update staff notification.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/staff-notifications/{notificationId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.edge_nodes.list List Commerce venue edge nodes. Contract: GET /api/venues/{venueId}/edge/nodes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List edge nodes.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/edge/nodes without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.edge_nodes.create Create a Commerce venue edge node. Contract: POST /api/venues/{venueId}/edge/nodes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "nodeLabel": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "nodeLabel": { "type": "string", "minLength": 1 }, "capabilities": { "type": "array", "items": { "type": "string" } }, "localEndpoint": { "type": "string" }, "notes": { "type": "string" }, "connectivityPolicy": { "type": "string" }, "metadata": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "nodeLabel" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create edge node.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/edge/nodes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.imports.list List Commerce venue imports. Contract: GET /api/venues/{venueId}/imports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: imports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List imports.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/imports without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.imports.create Create a Commerce venue import. Contract: POST /api/venues/{venueId}/imports Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: imports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "sourceType": { "type": "string" }, "sourceName": { "type": "string" }, "notes": { "type": "string" }, "requestedVerticalPack": { "type": "string" }, "draftSummary": { "type": "string" }, "sourceFile": { "type": "object", "properties": { "dataUrl": { "type": "string", "minLength": 1 }, "filename": { "type": "string" }, "name": { "type": "string" } }, "required": [ "dataUrl" ], "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create import.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/imports. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.imports.approve Approve a Commerce venue import. Contract: PUT /api/venues/{venueId}/imports/{importId}/approve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: imports:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "importId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Approve import.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/imports/{importId}/approve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.imports.reject Reject a Commerce venue import. Contract: PUT /api/venues/{venueId}/imports/{importId}/reject Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: imports:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "venueId": "example", "importId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 }, "reason": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Reject import.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/imports/{importId}/reject. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.imports.get Get a Commerce venue import. Contract: GET /api/venues/{venueId}/imports/{importId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: imports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example", "importId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get import.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/imports/{importId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.imports.asset.get Get a Commerce venue import asset. Contract: GET /api/venues/{venueId}/imports/{importId}/asset Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: imports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example", "importId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "importId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "importId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get import asset.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/imports/{importId}/asset without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.ops_voice.resolve Resolve Commerce ops voice input. Contract: POST /api/venues/{venueId}/ops/voice/resolve Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "transcript": { "type": "string" }, "utterance": { "type": "string" }, "audioDataUrl": { "type": "string" }, "mimeType": { "type": "string" }, "durationMs": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Resolve ops voice.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/ops/voice/resolve. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.ops_tickets.list List Commerce venue ops tickets. Contract: GET /api/venues/{venueId}/ops/tickets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: queues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List ops tickets.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/ops/tickets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.ops_live_state.get Get Commerce venue ops live state. Contract: GET /api/venues/{venueId}/ops/live-state Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: queues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get ops live state.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/ops/live-state without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.ops_live_stream_ticket.create Create a Commerce venue live stream ticket. Contract: POST /api/venues/{venueId}/ops/live-stream-ticket Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: queues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create live stream ticket.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/ops/live-stream-ticket. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.ops_tickets.update Update a Commerce venue ops ticket. Contract: PUT /api/venues/{venueId}/ops/tickets/{ticketId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: queues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "ticketId": "example", "status": "queued" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "ticketId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "queued", "active", "completed", "cancelled" ] }, "operatorNote": { "type": "string" }, "assignedStaffId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assignedSectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "expectedUpdatedAt": { "type": "number" }, "expectedStatus": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "ticketId", "status" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update ops ticket.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/ops/tickets/{ticketId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.team.list List Commerce venue team members. Contract: GET /api/venues/{venueId}/team Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List team.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/team without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.staff_identity_methods.list List Commerce staff identity methods. Contract: GET /api/venues/{venueId}/staff-identity-methods Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List staff identity methods.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/staff-identity-methods without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.team_sections.create Create a Commerce venue team section. Contract: POST /api/venues/{venueId}/team/sections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "name": { "type": "string", "minLength": 1 }, "zoneLabel": { "type": "string" }, "status": { "type": "string" }, "summary": { "type": "string" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create team section.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/team/sections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.team_members.create Create a Commerce venue team member. Contract: POST /api/venues/{venueId}/team/members Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "displayName": "example", "roleKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "userId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1 }, "roleKey": { "type": "string", "minLength": 1 }, "sectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "deviceType": { "type": "string" }, "notificationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "displayName", "roleKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create team member.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/team/members. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.team_members.update Update a Commerce venue team member. Contract: PUT /api/venues/{venueId}/team/members/{memberId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "memberId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "memberId": { "type": "string", "minLength": 1 }, "displayName": { "type": "string" }, "roleKey": { "type": "string" }, "sectionId": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "deviceType": { "type": "string" }, "notificationLabel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "memberId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update team member.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/team/members/{memberId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.team_members.identity_methods.create Create a Commerce team member identity method. Contract: POST /api/venues/{venueId}/team/members/{memberId}/identity-methods Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "memberId": "example", "methodType": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "memberId": { "type": "string", "minLength": 1 }, "id": { "type": "string" }, "methodType": { "type": "string", "minLength": 1 }, "credential": { "type": "string" }, "credentialHash": { "type": "string" }, "credentialSalt": { "type": "string" }, "credentialAlgorithm": { "type": "string" }, "label": { "type": "string" }, "status": { "type": "string" }, "mustChangeOnFirstUse": { "type": "boolean" }, "mustChangeOnNextUse": { "type": "boolean" }, "lastUsedAt": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "memberId", "methodType" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create team member identity method.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/team/members/{memberId}/identity-methods. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.security_policy.get Get Commerce venue security policy. Contract: GET /api/venues/{venueId}/security-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get security policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/security-policy without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.security_policy.update Update Commerce venue security policy. Contract: PATCH /api/venues/{venueId}/security-policy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "acceptedIdentityMethods": { "type": "array", "items": { "type": "string" } }, "pinLength": { "type": "number" }, "idleTimeoutSecondsByStationMode": { "type": "object", "properties": {}, "additionalProperties": {} }, "lockoutThresholdAttempts": { "type": "number" }, "lockoutWindowSeconds": { "type": "number" }, "lockoutDurationSeconds": { "type": "number" }, "discountStepUpThresholdCents": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update security policy.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/venues/{venueId}/security-policy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.operator_access_snapshot.get Get Commerce operator access snapshot. Contract: GET /api/venues/{venueId}/operator-access-snapshot Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get operator access snapshot.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/operator-access-snapshot without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.action_permissions.list List Commerce venue action permissions. Contract: GET /api/venues/{venueId}/action-permissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List action permissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/action-permissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.action_permissions.update Update Commerce venue action permission. Contract: PUT /api/venues/{venueId}/action-permissions/{actionKey} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "actionKey": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "actionKey": { "type": "string", "minLength": 1 }, "requiredRoleKeys": { "type": "array", "items": { "type": "string" } }, "stepUpRequired": { "type": "boolean" }, "payload": { "type": "object", "properties": {}, "additionalProperties": {} }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "actionKey" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update action permission.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/action-permissions/{actionKey}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.tables.floor_plan.get Get Commerce venue table floor plan. Contract: GET /api/venues/{venueId}/tables/floor-plan Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get floor plan.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/tables/floor-plan without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.tables.floor_plan.update Update Commerce venue table floor plan. Contract: PUT /api/venues/{venueId}/tables/floor-plan Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "floorPlan": { "type": "object", "properties": { "gridCols": { "type": "number" }, "gridRows": { "type": "number" }, "tables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "shape": { "type": "string" }, "capacity": { "type": "number" }, "sectionLabel": { "type": "string" }, "zone": { "type": "string" } }, "additionalProperties": false } }, "version": { "type": "number" }, "updatedAt": { "type": "string" } }, "additionalProperties": false }, "gridCols": { "type": "number" }, "gridRows": { "type": "number" }, "tables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "shape": { "type": "string" }, "capacity": { "type": "number" }, "sectionLabel": { "type": "string" }, "zone": { "type": "string" } }, "additionalProperties": false } }, "ifVersion": { "type": "number" }, "version": { "type": "number" }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update floor plan.", "additionalProperties": true } ``` Effects: May change state through PUT /api/venues/{venueId}/tables/floor-plan. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### venues.tables.qr_summary.get Get Commerce venue table QR summary. Contract: GET /api/venues/{venueId}/tables/qr-summary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "venueId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 } }, "required": [ "venueId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get table QR summary.", "additionalProperties": true } ``` Effects: Reads state through GET /api/venues/{venueId}/tables/qr-summary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### venues.tables.sync_qr Sync Commerce venue table QR codes. Contract: POST /api/venues/{venueId}/tables/sync-qr Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: venues:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "tables": [ { "id": "00000000-0000-4000-8000-000000000000" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "tables": { "minItems": 1, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "number": { "anyOf": [ { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, { "type": "null" } ] }, "zone": { "type": "string" }, "sectionLabel": { "type": "string" }, "label": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } }, "clientMutationId": { "type": "string", "minLength": 1 } }, "required": [ "venueId", "tables" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sync table QR.", "additionalProperties": true } ``` Effects: May change state through POST /api/venues/{venueId}/tables/sync-qr. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### assets.upload Upload a Commerce admin asset. Contract: PUT /api/admin/upload-asset Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: catalog:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "venueId": "example", "contentBase64": "example", "contentType": "image/png", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "venueId": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string", "minLength": 1, "maxLength": 14000000 }, "contentType": { "type": "string", "enum": [ "image/png", "image/jpeg", "image/webp", "image/gif" ] }, "fileName": { "type": "string", "minLength": 1 }, "assetKind": { "type": "string", "enum": [ "catalog-images", "voice-reviews" ] } }, "required": [ "venueId", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Upload asset.", "additionalProperties": true } ``` Effects: May change state through PUT /api/admin/upload-asset. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### catalog_images.generate Generate Commerce catalog images. Contract: POST /api/admin/generate-catalog-images Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: catalog:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "items": [ { "id": "00000000-0000-4000-8000-000000000000", "venueId": "example", "prompt": "example" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "minItems": 1, "maxItems": 50, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "venueId": { "type": "string", "minLength": 1 }, "prompt": { "type": "string", "minLength": 1 }, "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "id", "venueId", "prompt" ], "additionalProperties": false } }, "provider": { "type": "string" }, "model": { "type": "string" } }, "required": [ "items" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Generate catalog images.", "additionalProperties": true } ``` Effects: May change state through POST /api/admin/generate-catalog-images. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## TopoloCRM source contract Human reference: https://docs.topolo.app/systems/topolo-crm Machine reference: https://docs.topolo.app/machine/systems/topolo-crm.json Source revisions: apps/TopoloCRM@7b79b9768344e095e72f71c7f6d1a8dad22a156e Deploy targets: 2; implemented actions: 134; declared actions: 134; uncatalogued served routes: 2; mobile contracts: 1; route signals: 44. ### contacts.list List contacts. Contract: GET /api/contacts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example", "company": "example", "company_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "company": { "type": "string" }, "company_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" }, "job_title": { "type": "string" }, "employment_role": { "type": "string" }, "seniority": { "type": "string" }, "lead_status": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "lead_score_min": { "type": "number" }, "lead_score_max": { "type": "number" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "has_email": { "type": "boolean" }, "has_phone": { "type": "boolean" }, "has_mobile_phone": { "type": "boolean" }, "created_after": { "type": "string" }, "created_before": { "type": "string" }, "updated_after": { "type": "string" }, "updated_before": { "type": "string" }, "tags": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List contacts.", "additionalProperties": true } ``` Effects: Reads state through GET /api/contacts without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### contacts.get Get one contacts record. Contract: GET /api/contacts/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get contacts.", "additionalProperties": true } ``` Effects: Reads state through GET /api/contacts/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### contacts.create Create contacts. Contract: POST /api/contacts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "first": "example", "middle_name": "example", "last": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "first": { "type": "string" }, "middle_name": { "type": "string" }, "last": { "type": "string" }, "salutation": { "type": "string" }, "suffix": { "type": "string" }, "email": { "type": "string" }, "stageId": { "type": "string" }, "phone": { "type": "string" }, "mobile_phone": { "type": "string" }, "company": { "type": "string" }, "company_id": { "type": "string" }, "tags": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "instagram_url": { "type": "string" }, "tiktok_url": { "type": "string" }, "youtube_url": { "type": "string" }, "x_url": { "type": "string" }, "github_url": { "type": "string" }, "job_title": { "type": "string" }, "employment_role": { "type": "string" }, "seniority": { "type": "string" }, "department": { "type": "string" }, "lead_status": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "contact_accuracy_grade": { "type": "string" }, "education_level": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "address": { "type": "string" }, "linkedin_url": { "type": "string" }, "website_url": { "type": "string" }, "audience_primary_platform": { "type": "string" }, "audience_primary_url": { "type": "string" }, "audience_primary_handle": { "type": "string" }, "audience_follower_count_last_updated": { "type": "string" }, "audience_niche": { "type": "string" }, "company_domain": { "type": "string" }, "company_size": { "type": "string" }, "linkedin_headline": { "type": "string" }, "linkedin_about": { "type": "string" }, "linkedin_recent_experience": { "type": "string" }, "linkedin_inferred_timezone": { "type": "string" }, "linkedin_captured_at": { "type": "string" }, "latest_traffic_source": { "type": "string" }, "original_traffic_source": { "type": "string" }, "first_touch_campaign": { "type": "string" }, "last_touch_campaign": { "type": "string" }, "contact_owner": { "type": "string" }, "hubspot_team": { "type": "string" }, "traffic_source_date": { "type": "string" }, "original_traffic_drill_down_1": { "type": "string" }, "original_traffic_drill_down_2": { "type": "string" }, "latest_traffic_drill_down_1": { "type": "string" }, "latest_traffic_drill_down_2": { "type": "string" }, "lead_score": { "type": "number" }, "audience_follower_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "linkedin_followers": { "type": "number" }, "linkedin_connections": { "type": "number" }, "social_profiles": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "url": { "type": "string" }, "handle": { "type": "string" }, "follower_count": { "type": "number" }, "follower_count_last_updated": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "platform", "url" ], "additionalProperties": false } }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create contacts.", "additionalProperties": true } ``` Effects: May change state through POST /api/contacts. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### contacts.update Update one contacts record. Contract: PUT /api/contacts/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "first": { "type": "string" }, "middle_name": { "type": "string" }, "last": { "type": "string" }, "salutation": { "type": "string" }, "suffix": { "type": "string" }, "email": { "type": "string" }, "stageId": { "type": "string" }, "phone": { "type": "string" }, "mobile_phone": { "type": "string" }, "company": { "type": "string" }, "company_id": { "type": "string" }, "tags": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "instagram_url": { "type": "string" }, "tiktok_url": { "type": "string" }, "youtube_url": { "type": "string" }, "x_url": { "type": "string" }, "github_url": { "type": "string" }, "job_title": { "type": "string" }, "employment_role": { "type": "string" }, "seniority": { "type": "string" }, "department": { "type": "string" }, "lead_status": { "type": "string" }, "lifecycle_stage": { "type": "string" }, "contact_accuracy_grade": { "type": "string" }, "education_level": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "postal_code": { "type": "string" }, "address": { "type": "string" }, "linkedin_url": { "type": "string" }, "website_url": { "type": "string" }, "audience_primary_platform": { "type": "string" }, "audience_primary_url": { "type": "string" }, "audience_primary_handle": { "type": "string" }, "audience_follower_count_last_updated": { "type": "string" }, "audience_niche": { "type": "string" }, "company_domain": { "type": "string" }, "company_size": { "type": "string" }, "linkedin_headline": { "type": "string" }, "linkedin_about": { "type": "string" }, "linkedin_recent_experience": { "type": "string" }, "linkedin_inferred_timezone": { "type": "string" }, "linkedin_captured_at": { "type": "string" }, "latest_traffic_source": { "type": "string" }, "original_traffic_source": { "type": "string" }, "first_touch_campaign": { "type": "string" }, "last_touch_campaign": { "type": "string" }, "contact_owner": { "type": "string" }, "hubspot_team": { "type": "string" }, "traffic_source_date": { "type": "string" }, "original_traffic_drill_down_1": { "type": "string" }, "original_traffic_drill_down_2": { "type": "string" }, "latest_traffic_drill_down_1": { "type": "string" }, "latest_traffic_drill_down_2": { "type": "string" }, "lead_score": { "type": "number" }, "audience_follower_count": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "linkedin_followers": { "type": "number" }, "linkedin_connections": { "type": "number" }, "social_profiles": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "platform": { "type": "string" }, "url": { "type": "string" }, "handle": { "type": "string" }, "follower_count": { "type": "number" }, "follower_count_last_updated": { "type": "string" }, "is_primary": { "type": "boolean" } }, "required": [ "platform", "url" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update contacts.", "additionalProperties": true } ``` Effects: May change state through PUT /api/contacts/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### contacts.delete Delete one contacts record. Contract: DELETE /api/contacts/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete contacts.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/contacts/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### companies.list List companies. Contract: GET /api/companies Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: companies:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "page": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List companies.", "additionalProperties": true } ``` Effects: Reads state through GET /api/companies without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### companies.create Create companies. Contract: POST /api/companies Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: companies:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "description": "example", "website": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" }, "domain": { "type": "string" }, "phone": { "type": "string" }, "fax": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "industry": { "type": "string" }, "employee_range": { "type": "string" }, "revenue_range": { "type": "string" }, "primary_sub_industry": { "type": "string" }, "linkedin_url": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "logo_url": { "type": "string" }, "ticker": { "type": "string" }, "size": { "type": "string" }, "founded_year": { "type": "number" }, "employee_count": { "type": "number" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create companies.", "additionalProperties": true } ``` Effects: May change state through POST /api/companies. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### companies.get Get one companies record. Contract: GET /api/companies/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: companies:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get companies.", "additionalProperties": true } ``` Effects: Reads state through GET /api/companies/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### companies.update Update one companies record. Contract: PUT /api/companies/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: companies:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" }, "domain": { "type": "string" }, "phone": { "type": "string" }, "fax": { "type": "string" }, "email": { "type": "string" }, "address": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "industry": { "type": "string" }, "employee_range": { "type": "string" }, "revenue_range": { "type": "string" }, "primary_sub_industry": { "type": "string" }, "linkedin_url": { "type": "string" }, "external_id": { "type": "string" }, "external_profile_url": { "type": "string" }, "logo_url": { "type": "string" }, "ticker": { "type": "string" }, "size": { "type": "string" }, "founded_year": { "type": "number" }, "employee_count": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update companies.", "additionalProperties": true } ``` Effects: May change state through PUT /api/companies/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### companies.delete Delete one companies record. Contract: DELETE /api/companies/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: companies:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete companies.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/companies/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### deals.list List deals. Contract: GET /api/deals Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "page": 1, "limit": 1, "search": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "search": { "type": "string" }, "stage_id": { "type": "string" }, "pipeline_id": { "type": "string" }, "owner_id": { "type": "string" }, "company_id": { "type": "string" }, "contact_id": { "type": "string" }, "min_amount": { "type": "number" }, "max_amount": { "type": "number" }, "currency": { "type": "string" }, "min_probability": { "type": "number" }, "max_probability": { "type": "number" }, "expected_close_after": { "type": "string" }, "expected_close_before": { "type": "string" }, "created_after": { "type": "string" }, "created_before": { "type": "string" }, "updated_after": { "type": "string" }, "updated_before": { "type": "string" }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List deals.", "additionalProperties": true } ``` Effects: Reads state through GET /api/deals without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### deals.create Create deals. Contract: POST /api/deals Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "description": "example", "owner_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "owner_id": { "type": "string" }, "company_id": { "type": "string" }, "contact_id": { "type": "string" }, "currency": { "type": "string" }, "pipeline_id": { "type": "string" }, "stage_id": { "type": "string" }, "expected_close_date": { "type": "string" }, "amount_cents": { "type": "number" }, "amount": { "type": "number" }, "probability": { "type": "number" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create deals.", "additionalProperties": true } ``` Effects: May change state through POST /api/deals. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### deals.get Get one deals record. Contract: GET /api/deals/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get deals.", "additionalProperties": true } ``` Effects: Reads state through GET /api/deals/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### deals.update Update one deals record. Contract: PUT /api/deals/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "description": { "type": "string" }, "owner_id": { "type": "string" }, "company_id": { "type": "string" }, "contact_id": { "type": "string" }, "currency": { "type": "string" }, "pipeline_id": { "type": "string" }, "stage_id": { "type": "string" }, "expected_close_date": { "type": "string" }, "amount_cents": { "type": "number" }, "amount": { "type": "number" }, "probability": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update deals.", "additionalProperties": true } ``` Effects: May change state through PUT /api/deals/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### deals.delete Delete one deals record. Contract: DELETE /api/deals/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete deals.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/deals/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### deals.stage.update Update a CRM deal stage. Contract: PUT /api/deals/{id}/stage Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "stageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "stageId": { "type": "string", "minLength": 1 } }, "required": [ "id", "stageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update deal stage.", "additionalProperties": true } ``` Effects: May change state through PUT /api/deals/{id}/stage. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### deals.history.get Get CRM deal history. Contract: GET /api/deals/{id}/history Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get deal history.", "additionalProperties": true } ``` Effects: Reads state through GET /api/deals/{id}/history without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### deals.pipeline_board.get Get CRM deal pipeline board. Contract: GET /api/deals/pipeline/{pipelineId}/board Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: deals:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "pipelineId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "pipelineId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get deal pipeline board.", "additionalProperties": true } ``` Effects: Reads state through GET /api/deals/pipeline/{pipelineId}/board without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.list List CRM pipelines. Contract: GET /api/pipeline Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List pipelines.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pipeline without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.get Get a CRM pipeline. Contract: GET /api/pipeline/{pipelineId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "pipelineId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 } }, "required": [ "pipelineId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get pipeline.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pipeline/{pipelineId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.board.get Get a CRM pipeline board. Contract: GET /api/pipeline/{pipelineId}/board Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "pipelineId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "pipelineId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get pipeline board.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pipeline/{pipelineId}/board without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.stages.list List CRM pipeline stages. Contract: GET /api/pipeline/{pipelineId}/stages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "pipelineId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 } }, "required": [ "pipelineId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List pipeline stages.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pipeline/{pipelineId}/stages without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.structure.get Get CRM pipeline structure. Contract: GET /api/pipeline/{pipelineId}/structure Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "pipelineId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "pipelineId": { "type": "string", "minLength": 1 } }, "required": [ "pipelineId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get pipeline structure.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pipeline/{pipelineId}/structure without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.contact.status.get Get CRM contact pipeline status. Contract: GET /api/pipeline/{contactId}/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "contactId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get contact pipeline status.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pipeline/{contactId}/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.contact.history.get Get CRM contact pipeline history. Contract: GET /api/pipeline/{contactId}/history Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "contactId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get contact pipeline history.", "additionalProperties": true } ``` Effects: Reads state through GET /api/pipeline/{contactId}/history without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### pipeline.contact.add Add a CRM contact to a pipeline. Contract: POST /api/pipeline/{contactId}/add Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contactId": "example", "stageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "stageId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "stageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Add contact to pipeline.", "additionalProperties": true } ``` Effects: May change state through POST /api/pipeline/{contactId}/add. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### pipeline.contact.move Move a CRM contact in a pipeline. Contract: PUT /api/pipeline/{contactId}/move Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contactId": "example", "stageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "stageId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "stageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Move contact in pipeline.", "additionalProperties": true } ``` Effects: May change state through PUT /api/pipeline/{contactId}/move. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### pipeline.contact.remove Remove a CRM contact from a pipeline. Contract: DELETE /api/pipeline/{contactId}/remove Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "contactId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Remove contact from pipeline.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/pipeline/{contactId}/remove. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### pipeline.stages.update Update a CRM pipeline stage. Contract: PUT /api/pipeline/stages/{stageId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: pipeline:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "stageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "stageId": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "color": { "type": "string" }, "position": { "type": "number" } }, "required": [ "stageId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update pipeline stage.", "additionalProperties": true } ``` Effects: May change state through PUT /api/pipeline/stages/{stageId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### properties.list List properties. Contract: GET /api/properties Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "status": "example", "property_type": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "property_type": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "beds_min": { "type": "number" }, "beds_max": { "type": "number" }, "baths_min": { "type": "number" }, "baths_max": { "type": "number" }, "sqft_min": { "type": "number" }, "sqft_max": { "type": "number" }, "created_after": { "type": "string" }, "updated_after": { "type": "string" }, "sort_by": { "type": "string" }, "sort_order": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List properties.", "additionalProperties": true } ``` Effects: Reads state through GET /api/properties without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### properties.create Create properties. Contract: POST /api/properties Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "property_type": "example", "status": "example", "address_line1": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_type": { "type": "string" }, "status": { "type": "string" }, "address_line1": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "furnishing_status": { "type": "string" }, "owner_contact_id": { "type": "string" }, "owner_company_id": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "primary_photo_bytes_asset_id": { "type": "string" }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "beds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sqft": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lot_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "parking_spaces": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create properties.", "additionalProperties": true } ``` Effects: May change state through POST /api/properties. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### properties.get Get one properties record. Contract: GET /api/properties/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get properties.", "additionalProperties": true } ``` Effects: Reads state through GET /api/properties/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### properties.update Update one properties record. Contract: PUT /api/properties/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_type": { "type": "string" }, "status": { "type": "string" }, "address_line1": { "type": "string" }, "address_line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" }, "furnishing_status": { "type": "string" }, "owner_contact_id": { "type": "string" }, "owner_company_id": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "primary_photo_bytes_asset_id": { "type": "string" }, "latitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "beds": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "baths": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "sqft": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lot_size": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "parking_spaces": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update properties.", "additionalProperties": true } ``` Effects: May change state through PUT /api/properties/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### properties.delete Delete one properties record. Contract: DELETE /api/properties/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete properties.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/properties/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### listings.list List listings. Contract: GET /api/listings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "property_id": "00000000-0000-4000-8000-000000000000", "listing_type": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "price_min": { "type": "number" }, "price_max": { "type": "number" }, "canonical_completeness_min": { "type": "number" }, "canonical_completeness_max": { "type": "number" }, "created_after": { "type": "string" }, "updated_after": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List listings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/listings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### listings.create Create listings. Contract: POST /api/listings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "property_id": "00000000-0000-4000-8000-000000000000", "listing_type": "example", "internal_status": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" }, "permit_number": { "type": "string" }, "reference_code": { "type": "string" }, "description_short": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_long": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_amount": { "type": "number" }, "availability_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create listings.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### listings.get Get one listings record. Contract: GET /api/listings/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get listings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/listings/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### listings.update Update one listings record. Contract: PUT /api/listings/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" }, "permit_number": { "type": "string" }, "reference_code": { "type": "string" }, "description_short": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_long": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_amount": { "type": "number" }, "availability_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update listings.", "additionalProperties": true } ``` Effects: May change state through PUT /api/listings/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### listings.delete Delete one listings record. Contract: DELETE /api/listings/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete listings.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/listings/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### listings.validate Validate a CRM listing. Contract: POST /api/listings/{id}/validate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_type": { "type": "string" }, "internal_status": { "type": "string" }, "title": { "type": "string" }, "currency": { "type": "string" }, "permit_number": { "type": "string" }, "reference_code": { "type": "string" }, "description_short": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description_long": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price_amount": { "type": "number" }, "availability_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Validate listing.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings/{id}/validate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### listings.publications.list List CRM listing publications. Contract: GET /api/listings/{id}/publications Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List listing publications.", "additionalProperties": true } ``` Effects: Reads state through GET /api/listings/{id}/publications without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_connections.list List portal connections. Contract: GET /api/portal-connections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_connections:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "status": "example", "portal_key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "portal_key": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List portal connections.", "additionalProperties": true } ``` Effects: Reads state through GET /api/portal-connections without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_connections.create Create portal connections. Contract: POST /api/portal-connections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_connections:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "portal_key": "example", "account_name": "example", "connector_type": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create portal connections.", "additionalProperties": true } ``` Effects: May change state through POST /api/portal-connections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_connections.get Get one portal connections record. Contract: GET /api/portal-connections/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_connections:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get portal connections.", "additionalProperties": true } ``` Effects: Reads state through GET /api/portal-connections/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_connections.update Update one portal connections record. Contract: PUT /api/portal-connections/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_connections:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update portal connections.", "additionalProperties": true } ``` Effects: May change state through PUT /api/portal-connections/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_connections.delete Delete one portal connections record. Contract: DELETE /api/portal-connections/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_connections:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete portal connections.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/portal-connections/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_connections.health_check Run a CRM portal connection health check. Contract: POST /api/portal-connections/{id}/health-check Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_connections:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Run portal connection health check.", "additionalProperties": true } ``` Effects: May change state through POST /api/portal-connections/{id}/health-check. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_connections.disable Disable a CRM portal connection. Contract: POST /api/portal-connections/{id}/disable Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_connections:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_key": { "type": "string" }, "account_name": { "type": "string" }, "connector_type": { "type": "string" }, "auth_type": { "type": "string" }, "credentials_ref": { "type": "string" }, "market_region": { "type": "string" }, "status": { "type": "string" }, "connector_config": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Disable portal connection.", "additionalProperties": true } ``` Effects: May change state through POST /api/portal-connections/{id}/disable. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_leads.list List CRM portal leads. Contract: GET /api/portal-leads Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "portal_key": "example", "ingestion_status": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "portal_key": { "type": "string" }, "ingestion_status": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List portal leads.", "additionalProperties": true } ``` Effects: Reads state through GET /api/portal-leads without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_leads.get Get a CRM portal lead. Contract: GET /api/portal-leads/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get portal lead.", "additionalProperties": true } ``` Effects: Reads state through GET /api/portal-leads/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_leads.match Match a CRM portal lead. Contract: POST /api/portal-leads/{id}/match Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contact_id": { "type": "string" }, "create_if_missing": { "type": "boolean" }, "create_deal": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Match portal lead.", "additionalProperties": true } ``` Effects: May change state through POST /api/portal-leads/{id}/match. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_leads.create_contact Create a CRM contact from a portal lead. Contract: POST /api/portal-leads/{id}/create-contact Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "first": { "type": "string" }, "last": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create contact from portal lead.", "additionalProperties": true } ``` Effects: May change state through POST /api/portal-leads/{id}/create-contact. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_leads.create_deal Create a CRM deal from a portal lead. Contract: POST /api/portal-leads/{id}/create-deal Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "amount_cents": { "type": "number" }, "currency": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create deal from portal lead.", "additionalProperties": true } ``` Effects: May change state through POST /api/portal-leads/{id}/create-deal. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### lead_routing.rules.list List CRM lead routing rules. Contract: GET /api/lead-routing/rules Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List lead routing rules.", "additionalProperties": true } ``` Effects: Reads state through GET /api/lead-routing/rules without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### lead_routing.rules.create Create a CRM lead routing rule. Contract: POST /api/lead-routing/rules Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "portal_key": "example", "assigned_agent_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "portal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fallback_owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "auto_create_task": { "type": "boolean" }, "task_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create lead routing rule.", "additionalProperties": true } ``` Effects: May change state through POST /api/lead-routing/rules. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### lead_routing.rules.update Update a CRM lead routing rule. Contract: PUT /api/lead-routing/rules/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_leads:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "portal_key": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "fallback_owner_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "auto_create_task": { "type": "boolean" }, "task_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update lead routing rule.", "additionalProperties": true } ``` Effects: May change state through PUT /api/lead-routing/rules/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tasks.list List tasks. Contract: GET /api/tasks Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tasks:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "status": "example", "priority": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "owner_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List tasks.", "additionalProperties": true } ``` Effects: Reads state through GET /api/tasks without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### tasks.create Create tasks. Contract: POST /api/tasks Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tasks:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "description": "example", "status": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "owner_id": { "type": "string" }, "due_at": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create tasks.", "additionalProperties": true } ``` Effects: May change state through POST /api/tasks. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tasks.update Update one tasks record. Contract: PUT /api/tasks/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tasks:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string" }, "priority": { "type": "string" }, "entity_type": { "type": "string" }, "entity_id": { "type": "string" }, "owner_id": { "type": "string" }, "due_at": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update tasks.", "additionalProperties": true } ``` Effects: May change state through PUT /api/tasks/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tasks.delete Delete one tasks record. Contract: DELETE /api/tasks/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: tasks:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete tasks.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/tasks/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### showings.list List showings. Contract: GET /api/showings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: showings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "status": { "type": "string" }, "assigned_agent_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List showings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/showings without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### showings.create Create showings. Contract: POST /api/showings Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: showings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "portal_lead_event_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_lead_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "attendee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_at": { "type": "number" }, "duration_minutes": { "type": "number" }, "status": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create showings.", "additionalProperties": true } ``` Effects: May change state through POST /api/showings. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### showings.get Get one showings record. Contract: GET /api/showings/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: showings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get showings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/showings/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### showings.update Update one showings record. Contract: PUT /api/showings/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: showings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "portal_lead_event_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "attendee_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "attendee_phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "scheduled_at": { "type": "number" }, "duration_minutes": { "type": "number" }, "status": { "type": "string" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "assigned_agent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update showings.", "additionalProperties": true } ``` Effects: May change state through PUT /api/showings/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### showings.delete Delete one showings record. Contract: DELETE /api/showings/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: showings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete showings.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/showings/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### offers.list List offers. Contract: GET /api/offers Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: offers:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "status": { "type": "string" }, "contact_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List offers.", "additionalProperties": true } ``` Effects: Reads state through GET /api/offers without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### offers.create Create offers. Contract: POST /api/offers Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: offers:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "contact_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "amount_cents": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "expiry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contingencies": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create offers.", "additionalProperties": true } ``` Effects: May change state through POST /api/offers. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### offers.get Get one offers record. Contract: GET /api/offers/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: offers:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get offers.", "additionalProperties": true } ``` Effects: Reads state through GET /api/offers/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### offers.update Update one offers record. Contract: PUT /api/offers/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: offers:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "contact_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "amount_cents": { "type": "number" }, "currency": { "type": "string" }, "status": { "type": "string" }, "expiry_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "contingencies": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update offers.", "additionalProperties": true } ``` Effects: May change state through PUT /api/offers/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### offers.delete Delete one offers record. Contract: DELETE /api/offers/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: offers:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete offers.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/offers/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.list List transactions. Contract: GET /api/transactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "search": "example", "status": "example", "property_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "search": { "type": "string" }, "status": { "type": "string" }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "offer_id": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List transactions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/transactions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### transactions.create Create transactions. Contract: POST /api/transactions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "property_id": "00000000-0000-4000-8000-000000000000", "listing_id": "00000000-0000-4000-8000-000000000000", "offer_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "offer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "status": { "type": "string" }, "escrow_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "closing_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "assigned_coordinator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create transactions.", "additionalProperties": true } ``` Effects: May change state through POST /api/transactions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.get Get one transactions record. Contract: GET /api/transactions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get transactions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/transactions/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### transactions.update Update one transactions record. Contract: PUT /api/transactions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "property_id": { "type": "string" }, "listing_id": { "type": "string" }, "offer_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "type": "string" }, "status": { "type": "string" }, "escrow_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "closing_date": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "assigned_coordinator_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update transactions.", "additionalProperties": true } ``` Effects: May change state through PUT /api/transactions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.delete Delete one transactions record. Contract: DELETE /api/transactions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete transactions.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/transactions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.milestones.create Create a CRM transaction milestone. Contract: POST /api/transactions/{id}/milestones Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "status": { "type": "string" }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sort_order": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create transaction milestone.", "additionalProperties": true } ``` Effects: May change state through POST /api/transactions/{id}/milestones. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.milestones.update Update a CRM transaction milestone. Contract: PUT /api/transactions/{transactionId}/milestones/{milestoneId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "transactionId": "example", "milestoneId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "milestoneId": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "status": { "type": "string" }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sort_order": { "type": "number" } }, "required": [ "transactionId", "milestoneId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update transaction milestone.", "additionalProperties": true } ``` Effects: May change state through PUT /api/transactions/{transactionId}/milestones/{milestoneId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.checklist.create Create a CRM transaction checklist item. Contract: POST /api/transactions/{id}/checklist Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": { "type": "boolean" }, "status": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create transaction checklist item.", "additionalProperties": true } ``` Effects: May change state through POST /api/transactions/{id}/checklist. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.checklist.update Update a CRM transaction checklist item. Contract: PUT /api/transactions/{transactionId}/checklist/{itemId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: transactions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "transactionId": "example", "itemId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "itemId": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": { "type": "boolean" }, "status": { "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "due_at": { "anyOf": [ { "type": "number" }, { "type": "null" } ] } }, "required": [ "transactionId", "itemId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update transaction checklist item.", "additionalProperties": true } ``` Effects: May change state through PUT /api/transactions/{transactionId}/checklist/{itemId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.documents.create Create a CRM transaction document. Contract: POST /api/transactions/{id}/documents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: documents:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string" }, "url": { "type": "string" }, "document_type": { "type": "string" }, "status": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create transaction document.", "additionalProperties": true } ``` Effects: May change state through POST /api/transactions/{id}/documents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### transactions.documents.get Get a CRM transaction document. Contract: GET /api/transactions/{transactionId}/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: documents:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "transactionId": "example", "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "documentId": { "type": "string", "minLength": 1 } }, "required": [ "transactionId", "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get transaction document.", "additionalProperties": true } ``` Effects: Reads state through GET /api/transactions/{transactionId}/documents/{documentId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### transactions.documents.delete Delete a CRM transaction document. Contract: DELETE /api/transactions/{transactionId}/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: documents:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "transactionId": "example", "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transactionId": { "type": "string", "minLength": 1 }, "documentId": { "type": "string", "minLength": 1 } }, "required": [ "transactionId", "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete transaction document.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/transactions/{transactionId}/documents/{documentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### commissions.list List commissions. Contract: GET /api/commissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: commissions:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "transaction_id": "00000000-0000-4000-8000-000000000000", "status": "example", "page": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transaction_id": { "type": "string" }, "status": { "type": "string" }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List commissions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/commissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### commissions.create Create commissions. Contract: POST /api/commissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: commissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "transaction_id": "00000000-0000-4000-8000-000000000000", "recipient_type": "example", "recipient_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "transaction_id": { "type": "string" }, "recipient_type": { "type": "string" }, "recipient_id": { "type": "string" }, "recipient_name": { "type": "string" }, "status": { "type": "string" }, "split_bps": { "type": "number" }, "amount_cents": { "type": "number" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create commissions.", "additionalProperties": true } ``` Effects: May change state through POST /api/commissions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### commissions.update Update one commissions record. Contract: PUT /api/commissions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: commissions:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "transaction_id": { "type": "string" }, "recipient_type": { "type": "string" }, "recipient_id": { "type": "string" }, "recipient_name": { "type": "string" }, "status": { "type": "string" }, "split_bps": { "type": "number" }, "amount_cents": { "type": "number" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update commissions.", "additionalProperties": true } ``` Effects: May change state through PUT /api/commissions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### commissions.delete Delete one commissions record. Contract: DELETE /api/commissions/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: commissions:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete commissions.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/commissions/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### notes.list List CRM contact notes. Contract: GET /api/contacts/{id}/notes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: notes:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "page": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List contact notes.", "additionalProperties": true } ``` Effects: Reads state through GET /api/contacts/{id}/notes without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### notes.create Create a CRM contact note. Contract: POST /api/contacts/{id}/notes Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: notes:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "text": { "type": "string" }, "category": { "type": "string" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create contact note.", "additionalProperties": true } ``` Effects: May change state through POST /api/contacts/{id}/notes. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### notes.get Get a CRM contact note. Contract: GET /api/contacts/{contactId}/notes/{noteId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: notes:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "contactId": "example", "noteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "noteId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "noteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get contact note.", "additionalProperties": true } ``` Effects: Reads state through GET /api/contacts/{contactId}/notes/{noteId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### notes.update Update a CRM contact note. Contract: PUT /api/contacts/{contactId}/notes/{noteId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: notes:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contactId": "example", "noteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "noteId": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "text": { "type": "string" }, "category": { "type": "string" } }, "required": [ "contactId", "noteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update contact note.", "additionalProperties": true } ``` Effects: May change state through PUT /api/contacts/{contactId}/notes/{noteId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### notes.delete Delete a CRM contact note. Contract: DELETE /api/contacts/{contactId}/notes/{noteId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: notes:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "contactId": "example", "noteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "noteId": { "type": "string", "minLength": 1 } }, "required": [ "contactId", "noteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete contact note.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/contacts/{contactId}/notes/{noteId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### attachments.create Create a CRM contact attachment. Contract: POST /api/contacts/{id}/attachments Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: attachments:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "media_role": { "type": "string" }, "set_primary": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create contact attachment.", "additionalProperties": true } ``` Effects: May change state through POST /api/contacts/{id}/attachments. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### attachments.list List CRM contact attachments. Contract: GET /api/contacts/{id}/attachments Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: attachments:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List contact attachments.", "additionalProperties": true } ``` Effects: Reads state through GET /api/contacts/{id}/attachments without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### attachments.get Get a CRM attachment. Contract: GET /api/attachments/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: attachments:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get attachment.", "additionalProperties": true } ``` Effects: Reads state through GET /api/attachments/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### attachments.delete Delete a CRM attachment. Contract: DELETE /api/attachments/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: attachments:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete attachment.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/attachments/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### dashboard.real_estate.get Get CRM real estate dashboard. Contract: GET /api/dashboard/real-estate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "scope": "example", "window_days": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "scope": { "type": "string" }, "window_days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get real estate dashboard.", "additionalProperties": true } ``` Effects: Reads state through GET /api/dashboard/real-estate without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### dashboard.core.get Get CRM core dashboard. Contract: GET /api/dashboard/core Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get core dashboard.", "additionalProperties": true } ``` Effects: Reads state through GET /api/dashboard/core without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### saved_views.list List saved views. Contract: GET /api/saved-views Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "module_key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module_key": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List saved views.", "additionalProperties": true } ``` Effects: Reads state through GET /api/saved-views without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### saved_views.create Create saved views. Contract: POST /api/saved-views Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "module_key": "example", "required": true } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string" }, "module_key": { "type": "string" }, "required": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create saved views.", "additionalProperties": true } ``` Effects: May change state through POST /api/saved-views. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### saved_views.update Update one saved views record. Contract: PUT /api/saved-views/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string" }, "module_key": { "type": "string" }, "required": { "type": "boolean" }, "config": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update saved views.", "additionalProperties": true } ``` Effects: May change state through PUT /api/saved-views/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### saved_views.delete Delete one saved views record. Contract: DELETE /api/saved-views/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete saved views.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/saved-views/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### settings.org.get Get CRM organization settings. Contract: GET /api/settings/org Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get organization settings.", "additionalProperties": true } ``` Effects: Reads state through GET /api/settings/org without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### settings.org.update Update CRM organization settings. Contract: PUT /api/settings/org Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "module_settings": {}, "role_defaults": [ { "role_key": "example", "landing_path": "example" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module_settings": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, "role_defaults": { "type": "array", "items": { "type": "object", "properties": { "role_key": { "type": "string" }, "landing_path": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update organization settings.", "additionalProperties": true } ``` Effects: May change state through PUT /api/settings/org. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### search.run Run CRM search. Contract: GET /api/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: search:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Search CRM.", "additionalProperties": true } ``` Effects: Reads state through GET /api/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### import_export.preview Preview a CRM import. Contract: POST /api/import-export/preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "csvData": "example", "delimiter": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "csvData": { "type": "string" }, "delimiter": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preview import.", "additionalProperties": true } ``` Effects: May change state through POST /api/import-export/preview. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### import_export.execute Execute a CRM import. Contract: POST /api/import-export/execute Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "csvData": "example", "columnMapping": {}, "delimiter": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "csvData": { "type": "string" }, "columnMapping": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "delimiter": { "type": "string" }, "createCompanies": { "type": "boolean" }, "fileName": { "type": "string" }, "storeSourceRows": { "type": "boolean" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Execute import.", "additionalProperties": true } ``` Effects: May change state through POST /api/import-export/execute. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### import_export.template.get Get a CRM import template. Contract: GET /api/import-export/template Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "module_key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "module_key": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get import template.", "additionalProperties": true } ``` Effects: Reads state through GET /api/import-export/template without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### import_export.bulk Run a CRM bulk import. Contract: POST /api/import-export/bulk Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contacts": [ {} ], "companies": [ {} ], "notes": [ {} ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contacts": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "companies": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "notes": { "type": "array", "items": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Run bulk import.", "additionalProperties": true } ``` Effects: May change state through POST /api/import-export/bulk. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### import_export.export Export CRM data. Contract: GET /api/import-export/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "includeDeleted": true, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "includeDeleted": { "type": "boolean" }, "limit": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Export CRM data.", "additionalProperties": true } ``` Effects: Reads state through GET /api/import-export/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_sync.listing.publish Publish a CRM listing. Contract: POST /api/listings/{id}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_sync:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Publish listing.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings/{id}/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_sync.listing.unpublish Unpublish a CRM listing. Contract: POST /api/listings/{id}/unpublish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_sync:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Unpublish listing.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings/{id}/unpublish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_sync.listing.refresh Refresh CRM listing sync. Contract: POST /api/listings/{id}/refresh Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_sync:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Refresh listing sync.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings/{id}/refresh. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_sync.listing.retry Retry CRM listing sync. Contract: POST /api/listings/{id}/retry-sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_sync:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "portal_connection_ids": { "type": "array", "items": { "type": "string" } }, "force_refresh": { "type": "boolean" }, "dry_run": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Retry listing sync.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings/{id}/retry-sync. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### portal_sync.jobs.list List CRM listing sync jobs. Contract: GET /api/listings/{id}/sync-jobs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_sync:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List listing sync jobs.", "additionalProperties": true } ``` Effects: Reads state through GET /api/listings/{id}/sync-jobs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_sync.publications.get Get a CRM portal publication. Contract: GET /api/publications/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_sync:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get portal publication.", "additionalProperties": true } ``` Effects: Reads state through GET /api/publications/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### portal_sync.publication_jobs.list List CRM publication sync jobs. Contract: GET /api/publications/{id}/sync-jobs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: portal_sync:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List publication sync jobs.", "additionalProperties": true } ``` Effects: Reads state through GET /api/publications/{id}/sync-jobs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### real_estate_media.properties.list List CRM property media. Contract: GET /api/properties/{id}/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List property media.", "additionalProperties": true } ``` Effects: Reads state through GET /api/properties/{id}/media without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### real_estate_media.properties.create Create CRM property media. Contract: POST /api/properties/{id}/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "media_role": { "type": "string" }, "set_primary": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create property media.", "additionalProperties": true } ``` Effects: May change state through POST /api/properties/{id}/media. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### real_estate_media.properties.set_primary Set primary CRM property media. Contract: POST /api/properties/{propertyId}/media/{mediaId}/primary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "propertyId": "example", "mediaId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "propertyId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "propertyId", "mediaId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set primary property media.", "additionalProperties": true } ``` Effects: May change state through POST /api/properties/{propertyId}/media/{mediaId}/primary. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### real_estate_media.properties.delete Delete CRM property media. Contract: DELETE /api/properties/{propertyId}/media/{mediaId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: properties:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "propertyId": "example", "mediaId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "propertyId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "propertyId", "mediaId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete property media.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/properties/{propertyId}/media/{mediaId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### real_estate_media.listings.list List CRM listing media. Contract: GET /api/listings/{id}/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List listing media.", "additionalProperties": true } ``` Effects: Reads state through GET /api/listings/{id}/media without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### real_estate_media.listings.create Create CRM listing media. Contract: POST /api/listings/{id}/media Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "contentBase64": "example", "contentType": "example", "fileName": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "contentBase64": { "type": "string" }, "contentType": { "type": "string" }, "fileName": { "type": "string" }, "media_role": { "type": "string" }, "set_primary": { "anyOf": [ { "type": "boolean" }, { "type": "string" } ] } }, "required": [ "id", "contentBase64", "contentType", "fileName" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create listing media.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings/{id}/media. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### real_estate_media.listings.set_primary Set primary CRM listing media. Contract: POST /api/listings/{listingId}/media/{mediaId}/primary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "listingId": "example", "mediaId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "listingId", "mediaId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Set primary listing media.", "additionalProperties": true } ``` Effects: May change state through POST /api/listings/{listingId}/media/{mediaId}/primary. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### real_estate_media.listings.delete Delete CRM listing media. Contract: DELETE /api/listings/{listingId}/media/{mediaId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: listings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "listingId": "example", "mediaId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "listingId": { "type": "string", "minLength": 1 }, "mediaId": { "type": "string", "minLength": 1 } }, "required": [ "listingId", "mediaId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete listing media.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/listings/{listingId}/media/{mediaId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### real_estate_media.get Get CRM real estate media. Contract: GET /api/real-estate-media/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: attachments:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get real estate media.", "additionalProperties": true } ``` Effects: Reads state through GET /api/real-estate-media/{id} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.export Export CRM-owned organization data across all workspaces and storage concerns with credentials redacted and binary objects represented by metadata. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase CRM-owned organization data after active business work is closed and exact ERASE confirmation is supplied. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "example", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get CRM workspace summary widgets. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.archive Confirm a CRM workspace holds no records, then ask the platform to archive it. The workspace record itself belongs to Auth. Contract: DELETE /api/crm/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Archive CRM workspace.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/crm/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tickets.list List CRM tickets for the selected workspace. Contract: GET /api/tickets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "status": "example", "assignee_id": "00000000-0000-4000-8000-000000000000", "contact_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "status": { "type": "string" }, "assignee_id": { "type": "string" }, "contact_id": { "type": "string" }, "company_id": { "type": "string" }, "source": { "type": "string" }, "external_thread_id": { "type": "string" }, "limit": { "type": "integer", "minimum": 1, "maximum": 200 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/tickets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### tickets.get Get a CRM ticket and its messages. Contract: GET /api/tickets/{ticketId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "ticketId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 } }, "required": [ "ticketId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/tickets/{ticketId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### tickets.create Create a CRM ticket with an optional initial message. Contract: POST /api/tickets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "subject": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "subject": { "type": "string", "minLength": 1 }, "status": { "type": "string" }, "priority": { "type": "string" }, "contact_id": { "type": "string" }, "company_id": { "type": "string" }, "assignee_id": { "type": "string" }, "source": { "type": "string" }, "external_thread_id": { "type": "string" }, "message": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1 }, "direction": { "type": "string" }, "sender": { "type": "string" }, "recipients": { "type": "string" }, "message_id": { "type": "string" }, "in_reply_to": { "type": "string" } }, "required": [ "body" ], "additionalProperties": false } }, "required": [ "subject" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/tickets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tickets.messages.create Add a message to a CRM ticket. Contract: POST /api/tickets/{ticketId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "ticketId": "example", "body": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ticketId": { "type": "string", "minLength": 1 }, "body": { "type": "string", "minLength": 1 }, "direction": { "type": "string" }, "sender": { "type": "string" }, "recipients": { "type": "string" }, "message_id": { "type": "string" }, "in_reply_to": { "type": "string" } }, "required": [ "ticketId", "body" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/tickets/{ticketId}/messages. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### tickets.email.ingest Ingest an authenticated email event into CRM tickets. Contract: POST /api/tickets/ingest-email Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: contacts:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "from": "example", "to": "example", "subject": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "from": { "type": "string" }, "to": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "subject": { "type": "string" }, "body": { "type": "string" }, "messageId": { "type": "string" }, "inReplyTo": { "type": "string" } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/tickets/ingest-email. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## TopoloDocs source contract Human reference: https://docs.topolo.app/systems/topolo-docs Machine reference: https://docs.topolo.app/machine/systems/topolo-docs.json Source revisions: system-apps/TopoloDocs@content-sha256:f1156f3f8bfa67eea5ea769c2e21502bf7883b145bf30212f0ea11cc6a2b1140 Deploy targets: 2; implemented actions: 34; declared actions: 34; uncatalogued served routes: 0; mobile contracts: 0; route signals: 22. ### widget.get Get the TopoloOne widget summary for Docs. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.bootstrap Get the authenticated Docs user and organization context. Contract: GET /api/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/bootstrap without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspace.get Get the active Docs workspace projection. Contract: GET /api/docs/workspace Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/workspace without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.archive Archive an empty Docs workspace and purge its archived Docs data. Contract: DELETE /api/docs/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.list List active documentation spaces in the selected workspace. Contract: GET /api/docs/spaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.create Create a tenant-isolated documentation space. Contract: POST /api/docs/spaces Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "title": "example", "slug": "example", "description": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace", "public" ] }, "defaultLocale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "brand": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/spaces. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.get Get one documentation space from the selected workspace. Contract: GET /api/docs/spaces/{spaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces/{spaceId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.update Update a documentation space, visibility, locale, or brand configuration. Contract: PATCH /api/docs/spaces/{spaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "visibility": { "type": "string", "enum": [ "private", "workspace", "public" ] }, "defaultLocale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "brand": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/docs/spaces/{spaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.archive Archive a documentation space and remove it from active workspace navigation. Contract: DELETE /api/docs/spaces/{spaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/spaces/{spaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.documents.list List active documents in one documentation space. Contract: GET /api/docs/spaces/{spaceId}/documents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces/{spaceId}/documents without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.documents.create Create a document and its first immutable locale version. Contract: POST /api/docs/spaces/{spaceId}/documents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "title": { "type": "string" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "bodyMarkdown": { "type": "string" }, "locale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "sourceKind": { "type": "string", "enum": [ "native", "platform_repo", "repository_sync", "generated" ] }, "sourceRevision": { "type": "string" }, "sourcePath": { "type": "string" } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/spaces/{spaceId}/documents. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.sections.list List the configurable top-level sections a documentation space is organized into. Contract: GET /api/docs/spaces/{spaceId}/sections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/spaces/{spaceId}/sections without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### spaces.sections.create Create a top-level navigation section in one documentation space. Contract: POST /api/docs/spaces/{spaceId}/sections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "spaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/spaces/{spaceId}/sections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### spaces.sections.reorder Set the display order of every section in one documentation space. Contract: POST /api/docs/spaces/{spaceId}/sections/reorder Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "spaceId": "space_example", "sectionIds": [ "section_intro", "section_reference" ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sectionIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 160 }, "minItems": 1 } }, "required": [ "spaceId", "sectionIds" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Replaces the complete section display order for one documentation space. Verification: Call spaces.sections.list for the same spaceId and confirm the returned section order matches sectionIds. Recovery: 400 invalid_section_order: List the space sections and submit every section id exactly once. 403 forbidden: Use a credential with docs:write access to the selected Docs workspace. ### sections.update Rename a documentation section or change its slug. Contract: PATCH /api/docs/sections/{sectionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "sectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sectionId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "sectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/docs/sections/{sectionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sections.delete Delete a documentation section; its documents become unassigned rather than being deleted. Contract: DELETE /api/docs/sections/{sectionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "sectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "sectionId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "sectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/sections/{sectionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.section.set Move a document into a section of its space, or unassign it, and set its position within that section. Contract: PUT /api/docs/documents/{documentId}/section Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "sectionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "position": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PUT /api/docs/documents/{documentId}/section. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.list List active documents across the selected workspace. Contract: GET /api/docs/documents Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/documents without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### documents.get Get one document and its immutable version history. Contract: GET /api/docs/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/documents/{documentId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### documents.update Update native document metadata and review state. Contract: PATCH /api/docs/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 160 }, { "type": "null" } ] }, "title": { "type": "string" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "review" ] } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through PATCH /api/docs/documents/{documentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.archive Archive a native document and remove its publication pointer. Contract: DELETE /api/docs/documents/{documentId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/docs/documents/{documentId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.versions.list List immutable versions for one document. Contract: GET /api/docs/documents/{documentId}/versions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/documents/{documentId}/versions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### documents.versions.create Create an immutable locale-specific version and update full-text retrieval. Contract: POST /api/docs/documents/{documentId}/versions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example", "bodyMarkdown": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "title": { "type": "string" }, "summary": { "type": "string" }, "bodyMarkdown": { "type": "string" }, "locale": { "type": "string", "pattern": "^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$" }, "sourceRevision": { "type": "string" }, "sourcePath": { "type": "string" } }, "required": [ "documentId", "bodyMarkdown" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/documents/{documentId}/versions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.publish Publish one exact document version as an immutable public snapshot. Contract: POST /api/docs/documents/{documentId}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:publish Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 }, "versionId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/documents/{documentId}/publish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### documents.unpublish Remove public lookup pointers for a document. Contract: POST /api/docs/documents/{documentId}/unpublish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:publish Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "documentId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "documentId": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "documentId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/documents/{documentId}/unpublish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### search.query Run tenant-filtered full-text search across current locale versions. Contract: GET /api/docs/search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "q": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "q": { "type": "string", "minLength": 1, "maxLength": 500 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "q" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### public_search.query Search titles, summaries, and published body text in one public documentation space. Anonymous; only published versions are matched. Contract: GET /api/public/docs/{spaceSlug}/search.json Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "spaceSlug": "example", "q": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "spaceSlug": { "type": "string", "minLength": 1, "maxLength": 160 }, "q": { "type": "string", "minLength": 1, "maxLength": 500 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "spaceSlug", "q" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/public/docs/{spaceSlug}/search.json without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### search.ask Answer from tenant-filtered retrieved versions and return immutable citations. Contract: POST /api/docs/ask Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "query": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "query" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/ask. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspace.export Export spaces, documents, versions, and publication metadata for the selected workspace. Contract: GET /api/docs/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:export Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/docs/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### platform_corpus.sync Project the revisioned Topolo platform corpus into its platform-owned Docs workspace in an idempotent batch. Contract: POST /api/docs/platform-corpus/sync Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "cursor": 1, "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "cursor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/docs/platform-corpus/sync. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.catalog_drift.record Persist a catalog drift result and notify the platform operator. Contract: POST /api/operations/catalog-drift Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: validation:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "source": "example", "expectedDigest": "example", "actualDigest": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "source": { "type": "string", "minLength": 1, "maxLength": 240 }, "expectedDigest": { "type": "string", "minLength": 1, "maxLength": 160 }, "actualDigest": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "runId", "source", "expectedDigest", "actualDigest" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/catalog-drift. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.link_checks.fail Persist a failed link validation result and notify the platform operator. Contract: POST /api/operations/link-checks/failed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: validation:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "checkedUrl": "https://example.com", "reason": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "checkedUrl": { "type": "string", "maxLength": 2048, "format": "uri" }, "statusCode": { "anyOf": [ { "type": "integer", "minimum": 100, "maximum": 599 }, { "type": "null" } ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "runId", "checkedUrl", "reason" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/link-checks/failed. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.publishes.complete Persist a completed documentation publish and notify the platform operator. Contract: POST /api/operations/publishes/completed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "revision": "example", "environment": "development", "publishedUrl": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "string", "minLength": 1, "maxLength": 160 }, "environment": { "type": "string", "enum": [ "development", "staging", "production" ] }, "publishedUrl": { "type": "string", "maxLength": 2048, "format": "uri" } }, "required": [ "runId", "revision", "environment", "publishedUrl" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/publishes/completed. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### operations.publishes.fail Persist a failed documentation publish and notify the platform operator. Contract: POST /api/operations/publishes/failed Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: docs:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "runId": "example", "revision": "example", "environment": "development", "reason": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "runId": { "type": "string", "minLength": 1, "maxLength": 160 }, "revision": { "type": "string", "minLength": 1, "maxLength": 160 }, "environment": { "type": "string", "enum": [ "development", "staging", "production" ] }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "runId", "revision", "environment", "reason" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/operations/publishes/failed. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## TopoloMDM source contract Human reference: https://docs.topolo.app/systems/topolo-mdm Machine reference: https://docs.topolo.app/machine/systems/topolo-mdm.json Source revisions: apps/TopoloMDM@eaf9d5e2bc22504ac71ee1143b78da9e3b1b810f Deploy targets: 2; implemented actions: 23; declared actions: 23; uncatalogued served routes: 0; mobile contracts: 1; route signals: 48. ### workspaces.delete Archive an empty MDM workspace. The platform owns the workspace record; this app confirms it holds no devices and asks Auth to archive it. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.data.export Export the MDM-owned device, enrollment, notification, assignment, and retained event data for one authorized workspace with credentials redacted. Contract: GET /api/workspaces/{workspaceId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/workspaces/{workspaceId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.data.erase Permanently erase all MDM-owned data for one authorized workspace while preserving the canonical Auth workspace and credentials. Contract: DELETE /api/workspaces/{workspaceId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### fleet.get Get the MDM OpenClaw fleet report. Contract: GET /api/openclaw/fleet Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get fleet report.", "additionalProperties": true } ``` Effects: Reads state through GET /api/openclaw/fleet without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### events.list List MDM OpenClaw events. Contract: GET /api/openclaw/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: reports:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "since": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "since": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 500 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List fleet events.", "additionalProperties": true } ``` Effects: Reads state through GET /api/openclaw/events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### operator_events.list List MDM operator events. Contract: GET /api/events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List operator events.", "additionalProperties": true } ``` Effects: Reads state through GET /api/events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### enrollment_sessions.create Create an MDM enrollment session. Contract: POST /api/enrollment-sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:control Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "workspace_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create enrollment session.", "additionalProperties": true } ``` Effects: May change state through POST /api/enrollment-sessions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### devices.list List MDM devices. Contract: GET /api/devices Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List devices.", "additionalProperties": true } ``` Effects: Reads state through GET /api/devices without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### devices.admin_list List MDM devices with admin scope. Contract: GET /api/admin/devices Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:admin Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "filter_workspace_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "filter_workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin list devices.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/devices without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### devices.delete Delete an MDM device. Contract: DELETE /api/devices/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete device.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/devices/{deviceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### devices.dump.get Get an MDM device dump. Contract: GET /api/device-dump/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get device dump.", "additionalProperties": true } ``` Effects: Reads state through GET /api/device-dump/{deviceId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### devices.debug.get Get MDM device debug data. Contract: GET /api/devices/{deviceId}/debug Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get device debug.", "additionalProperties": true } ``` Effects: Reads state through GET /api/devices/{deviceId}/debug without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### devices.info.update Update MDM device info. Contract: POST /api/device-info/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "installedPackages": { "type": "array", "items": {} }, "metrics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update device info.", "additionalProperties": true } ``` Effects: May change state through POST /api/device-info/{deviceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### devices.account.register Register an MDM device account. Contract: POST /api/register-account/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "deviceId": "example", "accountNumber": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "minLength": 1 } }, "required": [ "deviceId", "accountNumber" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Register device account.", "additionalProperties": true } ``` Effects: May change state through POST /api/register-account/{deviceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### devices.account_id.update Update an MDM device account id. Contract: POST /api/update-account-id/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "deviceId": "example", "accountNumber": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "accountNumber": { "type": "string", "minLength": 1 } }, "required": [ "deviceId", "accountNumber" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update device account id.", "additionalProperties": true } ``` Effects: May change state through POST /api/update-account-id/{deviceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### devices.account_info.update Update MDM device account info. Contract: POST /api/update-account-info/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "deviceId": "example", "accountInfo": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "accountInfo": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "deviceId", "accountInfo" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update device account info.", "additionalProperties": true } ``` Effects: May change state through POST /api/update-account-info/{deviceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### device_profiles.list List MDM device profiles. Contract: GET /api/device-profiles Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: policies:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspace_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List device profiles.", "additionalProperties": true } ``` Effects: Reads state through GET /api/device-profiles without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### device_profiles.get Get an MDM device profile. Contract: GET /api/device-profiles/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: policies:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get device profile.", "additionalProperties": true } ``` Effects: Reads state through GET /api/device-profiles/{deviceId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### device_profiles.upsert Upsert an MDM device profile. Contract: PUT /api/device-profiles/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: policies:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "deviceId": "example", "profile": {} } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 }, "profile": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "deviceId", "profile" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Upsert device profile.", "additionalProperties": true } ``` Effects: May change state through PUT /api/device-profiles/{deviceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### commands.enqueue Enqueue an MDM device command. Contract: POST /api/enqueue Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: commands:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "deviceId": "example", "command": { "id": "00000000-0000-4000-8000-000000000000", "action": "example" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 }, "command": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "action": { "type": "string", "minLength": 1 } }, "required": [ "id", "action" ], "additionalProperties": {} } }, "required": [ "deviceId", "command" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Enqueue command.", "additionalProperties": true } ``` Effects: May change state through POST /api/enqueue. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### commands.clear Clear queued MDM device commands. Contract: POST /api/clear-commands Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: commands:invoke Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "minLength": 1 }, "deviceId": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Clear commands.", "additionalProperties": true } ``` Effects: May change state through POST /api/clear-commands. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### commands.history.get Get MDM command history for a device. Contract: GET /api/command-history/{deviceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: devices:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "deviceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "deviceId": { "type": "string", "minLength": 1 }, "workspace_id": { "type": "string", "minLength": 1 } }, "required": [ "deviceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get command history.", "additionalProperties": true } ``` Effects: Reads state through GET /api/command-history/{deviceId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## TopoloMessages source contract Human reference: https://docs.topolo.app/systems/topolo-messages Machine reference: https://docs.topolo.app/machine/systems/topolo-messages.json Source revisions: apps/TopoloMessages@8ad475d8acff71d013ffa7e496968950a9516a68 Deploy targets: 3; implemented actions: 31; declared actions: 32; uncatalogued served routes: 0; mobile contracts: 1; route signals: 43. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: declared_unserved. No matching served route was extracted from canonical staging source. Permission: context:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### bootstrap.get Get Messages workspace bootstrap data. Contract: GET /api/messages/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get messages bootstrap.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/bootstrap without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### analytics.get Get messaging volume, delivery, contact consent, and campaign health metrics. Contract: GET /api/messages/analytics Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get messages analytics.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/analytics without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### provider_status.get Get WhatsApp provider queue, webhook, and runtime configuration status for a Messages workspace. Contract: GET /api/messages/provider-status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get messages provider status.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/provider-status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### conversations.list List message conversations. Contract: GET /api/messages/conversations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List conversations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/conversations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### contacts.list List WhatsApp contacts, consent state, and recent conversation activity. Contract: GET /api/messages/contacts Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "consentStatus": "unknown", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "consentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 250 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List contacts.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/contacts without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### contacts.update Update a WhatsApp contact consent state. Contract: PATCH /api/messages/contacts/{contactId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:send Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contactId": "example", "consentStatus": "unknown" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contactId": { "type": "string", "minLength": 1 }, "consentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] } }, "required": [ "contactId", "consentStatus" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update contact.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/messages/contacts/{contactId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### conversations.update Update a messaging conversation state, assignment, follow-up, or contact context. Contract: PATCH /api/messages/conversations/{conversationId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:send Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "conversationId": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "open", "pending", "resolved", "archived" ] }, "assignedToUserId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] }, "assignToMe": { "type": "boolean" }, "clearAssignment": { "type": "boolean" }, "markRead": { "type": "boolean" }, "contactConsentStatus": { "type": "string", "enum": [ "unknown", "opted_in", "opted_out" ] }, "priority": { "type": "string", "enum": [ "normal", "high", "urgent" ] }, "internalNote": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "followUpAt": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$" }, { "type": "null" } ] } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update conversation.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/messages/conversations/{conversationId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### messages.send Send an outbound message. Contract: POST /api/messages/messages/send Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: messages:send Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "numberId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "numberId": { "type": "string", "minLength": 1 }, "messageType": { "type": "string", "enum": [ "text", "template" ] }, "body": { "type": "string", "minLength": 1 }, "templateName": { "type": "string", "minLength": 1 }, "recipientPhone": { "type": "string", "minLength": 1 }, "phoneNumber": { "type": "string", "minLength": 1 }, "waId": { "type": "string", "minLength": 1 }, "recipientName": { "type": "string", "minLength": 1 }, "payload": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "numberId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Send message.", "additionalProperties": true } ``` Effects: May change state through POST /api/messages/messages/send. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.list List messaging campaigns. Contract: GET /api/messages/campaigns Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: campaigns:manage Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List campaigns.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/campaigns without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### templates.list List WhatsApp message templates. Contract: GET /api/messages/templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: campaigns:manage Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List templates.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/templates without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### templates.create Register a WhatsApp message template. Contract: POST /api/messages/templates Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: campaigns:manage Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "sampleBody": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "language": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "marketing", "utility", "authentication", "service" ] }, "sampleBody": { "type": "string", "minLength": 1 } }, "required": [ "name", "sampleBody" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create template.", "additionalProperties": true } ``` Effects: May change state through POST /api/messages/templates. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### outbound_jobs.list List recent outbound WhatsApp delivery jobs. Contract: GET /api/messages/outbound-jobs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "status": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List outbound jobs.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/outbound-jobs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### webhook_events.list List recent WhatsApp webhook intake events. Contract: GET /api/messages/webhook-events Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "status": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List webhook events.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/webhook-events without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### campaigns.create Create a messaging campaign. Contract: POST /api/messages/campaigns Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: campaigns:manage Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "numberId": { "type": "string", "minLength": 1 }, "templateName": { "type": "string", "minLength": 1 }, "templateLanguage": { "type": "string", "minLength": 1 }, "templateParameters": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "templateParametersText": { "type": "string", "minLength": 1 }, "audienceSource": { "type": "string", "minLength": 1 }, "scheduledAt": { "type": "string", "minLength": 1 }, "recipientsText": { "type": "string", "minLength": 1 }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "phoneNumber": { "type": "string", "minLength": 1 }, "phone": { "type": "string", "minLength": 1 }, "recipientPhone": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "recipientName": { "type": "string", "minLength": 1 } }, "additionalProperties": false } } }, "required": [ "name" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create campaign.", "additionalProperties": true } ``` Effects: May change state through POST /api/messages/campaigns. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### campaigns.recipients.list List recipients and delivery state for a messaging campaign. Contract: GET /api/messages/campaigns/{campaignId}/recipients Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: campaigns:manage Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "campaignId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "campaignId": { "type": "string", "minLength": 1 } }, "required": [ "campaignId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List campaign recipients.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/campaigns/{campaignId}/recipients without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### automations.list List messaging automations. Contract: GET /api/messages/automations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: automations:manage Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List automations.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/automations without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### automations.runs.list List recent messaging automation execution runs. Contract: GET /api/messages/automations/runs Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: automations:manage Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example", "automationId": "example", "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "automationId": { "type": "string", "minLength": 1 }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List automation runs.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/automations/runs without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### campaigns.launch Queue a drafted messaging campaign for pending recipients. Contract: POST /api/messages/campaigns/{campaignId}/launch Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: campaigns:manage Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "campaignId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "campaignId": { "type": "string", "minLength": 1 } }, "required": [ "campaignId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Launch campaign.", "additionalProperties": true } ``` Effects: May change state through POST /api/messages/campaigns/{campaignId}/launch. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### automations.create Create a messaging automation. Contract: POST /api/messages/automations Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: automations:manage Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "triggerType": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "triggerType": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "numberId": { "type": "string", "minLength": 1 }, "definition": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "name", "triggerType" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create automation.", "additionalProperties": true } ``` Effects: May change state through POST /api/messages/automations. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### numbers.list List messaging phone numbers. Contract: GET /api/messages/numbers Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: numbers:manage Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List numbers.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/numbers without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### workspaces.delete Delete an empty, non-default Messages workspace. Contract: DELETE /api/messages/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Delete workspace.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/messages/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### contacts.get Get one Messages contact. Contract: GET /api/messages/contacts/{contactId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "contactId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "contactId": { "type": "string", "minLength": 1 } }, "required": [ "contactId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get contact.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/contacts/{contactId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### conversations.get Get one Messages conversation. Contract: GET /api/messages/conversations/{conversationId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get conversation.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/conversations/{conversationId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### conversation_messages.list List message history for one conversation. Contract: GET /api/messages/conversations/{conversationId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "conversationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "conversationId": { "type": "string", "minLength": 1 } }, "required": [ "conversationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List conversation messages.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/conversations/{conversationId}/messages without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### templates.get Get one Messages template. Contract: GET /api/messages/templates/{templateId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "templateId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "templateId": { "type": "string", "minLength": 1 } }, "required": [ "templateId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get template.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/templates/{templateId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### campaigns.get Get one Messages campaign. Contract: GET /api/messages/campaigns/{campaignId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "campaignId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 }, "campaignId": { "type": "string", "minLength": 1 } }, "required": [ "campaignId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get campaign.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/campaigns/{campaignId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### channels.connect Connect a messaging channel to the active Messages workspace by exchanging a provider authorization code. WhatsApp today; the same action serves other channels. Contract: POST /api/messages/channels/connect Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: numbers:manage Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "code": "example", "accountId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "channel": { "type": "string", "enum": [ "whatsapp" ] }, "code": { "type": "string", "minLength": 1 }, "accountId": { "type": "string", "minLength": 1 } }, "required": [ "code", "accountId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Connect channel.", "additionalProperties": true } ``` Effects: May change state through POST /api/messages/channels/connect. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### messages.semantic_search Find workspace-scoped message content by meaning without storing plaintext in the semantic index. Contract: POST /api/messages/semantic-search Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: inbox:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "searchText": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "searchText": { "type": "string", "minLength": 2, "maxLength": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 25 } }, "required": [ "searchText" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Workspace-scoped semantic message matches with decrypted content returned only to the authorized caller.", "additionalProperties": true } ``` Effects: Reads state through POST /api/messages/semantic-search without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.protection.canary Verify canonical Messages protected fields decrypt under the active D1 application root. Contract: GET /api/messages/privacy/protection/canary Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Messages protection canary result without plaintext or key material.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/privacy/protection/canary without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.export Export all Messages records for one authorized workspace with protected content decrypted for the requester. Contract: GET /api/messages/privacy/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Workspace-scoped Messages data export.", "additionalProperties": true } ``` Effects: Reads state through GET /api/messages/privacy/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### privacy.delete Permanently erase all Messages content in one authorized workspace while retaining its workspace identity. Contract: DELETE /api/messages/privacy Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Workspace-scoped Messages erasure result.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/messages/privacy. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## TopoloOne source contract Human reference: https://docs.topolo.app/systems/topolo-one Machine reference: https://docs.topolo.app/machine/systems/topolo-one.json Source revisions: apps/TopoloOne@a6c9fe5faa3e4cea7302101db6f6c1df60495711 Deploy targets: 3; implemented actions: 24; declared actions: 24; uncatalogued served routes: 0; mobile contracts: 1; route signals: 40. ### workspaces.delete Archive an empty workspace: TopoloOne confirms it holds no data, then the platform archives the record. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/workspaces/{workspaceId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.data.export Export TopoloOne-owned launch, push, billing, cache, and workspace-mirror data for the authenticated organization with credential fields redacted. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase TopoloOne-owned organization data after refusing active billing subscriptions, with explicit pending verification for eventually consistent KV. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### apps.list List apps visible in TopoloOne. Contract: GET /api/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List launcher apps.", "additionalProperties": true } ``` Effects: Reads state through GET /api/apps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### dashboard.get Get the current organization launcher catalog, preferences, users, and canonical store icons. Contract: GET /api/dashboard Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "org_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "org_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "data": { "type": "object", "properties": { "services": { "type": "array", "items": {} }, "availableServices": { "type": "array", "items": {} } }, "required": [ "services", "availableServices" ], "additionalProperties": {} } }, "required": [ "data" ], "additionalProperties": false } ``` Effects: Reads state through GET /api/dashboard without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### checkout.quote Quote a cart checkout. Contract: POST /api/cart/quote Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: entitlements:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "items": [ { "slug": "example" } ], "appSlugs": [ "example" ], "seats": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "slug" ], "additionalProperties": false } }, "appSlugs": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "billing": { "type": "string", "enum": [ "monthly", "annual" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Quote checkout.", "additionalProperties": true } ``` Effects: May change state through POST /api/cart/quote. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### checkout.create Create a checkout session. Contract: POST /api/cart/checkout Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workflows:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "items": [ { "slug": "example" } ], "appSlugs": [ "example" ], "seats": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "minLength": 1 }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "slug" ], "additionalProperties": false } }, "appSlugs": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "seats": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "billing": { "type": "string", "enum": [ "monthly", "annual" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create checkout.", "additionalProperties": true } ``` Effects: May change state through POST /api/cart/checkout. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widgets.aggregate Call POST /api/widgets. Contract: POST /api/widgets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "contextKey": "example", "services": [ { "id": "00000000-0000-4000-8000-000000000000" } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "contextKey": { "type": "string", "minLength": 1 }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "settings": {}, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "supportedContexts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "isInstalled": { "type": "boolean" }, "widgetEndpoint": { "type": "string", "minLength": 1 }, "widget_endpoint": { "type": "string", "minLength": 1 }, "widgetOrigin": { "type": "string", "minLength": 1 }, "widget_origin": { "type": "string", "minLength": 1 }, "widgetsEnabled": { "type": "boolean" }, "widget_enabled": { "type": "boolean" }, "refreshInterval": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Widgets Aggregate.", "additionalProperties": true } ``` Effects: May change state through POST /api/widgets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget_snapshots.create Call POST /api/widget-snapshots. Contract: POST /api/widget-snapshots Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: widgets:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "preset": "example", "contextKey": "example", "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "preset": { "type": "string", "minLength": 1 }, "contextKey": { "type": "string", "minLength": 1 }, "appId": { "type": "string", "minLength": 1 }, "service": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "settings": {}, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "supportedContexts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "isInstalled": { "type": "boolean" }, "widgetEndpoint": { "type": "string", "minLength": 1 }, "widget_endpoint": { "type": "string", "minLength": 1 }, "widgetOrigin": { "type": "string", "minLength": 1 }, "widget_origin": { "type": "string", "minLength": 1 }, "widgetsEnabled": { "type": "boolean" }, "widget_enabled": { "type": "boolean" }, "refreshInterval": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} }, { "type": "null" } ] }, "services": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "settings": {}, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "minLength": 1 }, "supportedContexts": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "isInstalled": { "type": "boolean" }, "widgetEndpoint": { "type": "string", "minLength": 1 }, "widget_endpoint": { "type": "string", "minLength": 1 }, "widgetOrigin": { "type": "string", "minLength": 1 }, "widget_origin": { "type": "string", "minLength": 1 }, "widgetsEnabled": { "type": "boolean" }, "widget_enabled": { "type": "boolean" }, "refreshInterval": { "type": "number" } }, "required": [ "id" ], "additionalProperties": {} } }, "metricKeys": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Widget Snapshots Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/widget-snapshots. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.create Call POST /api/apps. Contract: POST /api/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "base_url": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "icon": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "developer": { "type": "string", "minLength": 1 }, "version": { "type": "string", "minLength": 1 }, "base_url": { "type": "string", "minLength": 1 }, "launch_url_template": { "type": "string", "minLength": 1 }, "required_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "optional_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "status": { "type": "string", "enum": [ "active", "inactive", "maintenance" ] }, "is_system_app": { "type": "boolean" } }, "required": [ "id", "name", "base_url" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/apps. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.update Call PATCH /api/apps/{id}. Contract: PATCH /api/apps/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "description": { "type": "string", "minLength": 1 }, "icon": { "type": "string", "minLength": 1 }, "required_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "optional_permissions": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "base_url": { "type": "string", "minLength": 1 }, "launch_url_template": { "type": "string", "minLength": 1 }, "category": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "active", "inactive", "maintenance" ] }, "is_system_app": { "type": "boolean" } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps Update.", "additionalProperties": true } ``` Effects: May change state through PATCH /api/apps/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### apps.delete Call DELETE /api/apps/{id}. Contract: DELETE /api/apps/{id} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "id": { "type": "string", "minLength": 1 } }, "required": [ "id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Apps Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/apps/{id}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### billing.organization_preview Call POST /api/billing/organizations/{orgId}/preview. Contract: POST /api/billing/organizations/{orgId}/preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "orgId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "orgId": { "type": "string", "minLength": 1 }, "organizationId": { "type": "string", "minLength": 1 }, "targetSeatQuantity": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "seatSummary": {} }, "required": [ "orgId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Billing Organization Preview.", "additionalProperties": true } ``` Effects: May change state through POST /api/billing/organizations/{orgId}/preview. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### push_subscriptions.create Call POST /api/push/subscriptions. Contract: POST /api/push/subscriptions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: notifications:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "endpoint": "example", "keys": { "p256dh": "example", "auth": "example" } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpoint": { "type": "string", "minLength": 1 }, "keys": { "type": "object", "properties": { "p256dh": { "type": "string", "minLength": 1 }, "auth": { "type": "string", "minLength": 1 } }, "required": [ "p256dh", "auth" ], "additionalProperties": false } }, "required": [ "endpoint", "keys" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Push Subscriptions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/push/subscriptions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### push_subscriptions.delete Call DELETE /api/push/subscriptions. Contract: DELETE /api/push/subscriptions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: notifications:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "endpoint": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "endpoint": { "type": "string", "minLength": 1 } }, "required": [ "endpoint" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Push Subscriptions Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/push/subscriptions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### push.vapid_key.get Call GET /api/push/vapid-key. Contract: GET /api/push/vapid-key Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Push Vapid Key Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/push/vapid-key without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### launch.get Call GET /api/launch/{appId}. Contract: GET /api/launch/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: launcher:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Launch Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/launch/{appId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### launch.create Call POST /api/launch/{appId}. Contract: POST /api/launch/{appId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: launches:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Launch Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/launch/{appId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### launch.secure_token.create Call POST /api/launch/secure-token. Contract: POST /api/launch/secure-token Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: launches:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example", "callbackUrl": "https://example.com" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "callbackUrl": { "type": "string", "minLength": 1 } }, "required": [ "appId", "callbackUrl" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Launch Secure Token Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/launch/secure-token. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### track.create Call POST /api/track. Contract: POST /api/track Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: dashboard:read Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "appId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "appId": { "type": "string", "minLength": 1 }, "metadata": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "appId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Track Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/track. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### admin.status.get Call GET /api/admin/status. Contract: GET /api/admin/status Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Status Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/status without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.apps.list Call GET /api/admin/apps. Contract: GET /api/admin/apps Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Apps List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/apps without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### admin.categories.list Call GET /api/admin/categories. Contract: GET /api/admin/categories Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: apps:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Admin Categories List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/admin/categories without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ## TopoloP2P source contract Human reference: https://docs.topolo.app/systems/topolo-p2p Machine reference: https://docs.topolo.app/machine/systems/topolo-p2p.json Source revisions: system-apps/TopoloP2P@0ee9f3cb3b2f95f59806528354a9c86bf9226e23 Deploy targets: 2; implemented actions: 20; declared actions: 20; uncatalogued served routes: 0; mobile contracts: 1; route signals: 19. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: directory:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### directory.capabilities.list List P2P directory capabilities. Contract: GET /api/directory/capabilities Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List P2P capabilities.", "additionalProperties": true } ``` Effects: Reads state through GET /api/directory/capabilities without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### directory.capabilities.get Get one public P2P directory capability. Contract: GET /api/directory/capabilities/{capabilityId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "capabilityId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capabilityId": { "type": "string", "minLength": 1 } }, "required": [ "capabilityId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/directory/capabilities/{capabilityId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### connections.list List P2P connections. Contract: GET /api/connections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: directory:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List P2P connections.", "additionalProperties": true } ``` Effects: Reads state through GET /api/connections without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### connections.create Create a P2P connection. Contract: POST /api/connections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: connections:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "counterparty_org_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "counterparty_org_id": { "type": "string", "minLength": 1 }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] } }, "required": [ "counterparty_org_id" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create P2P connection.", "additionalProperties": true } ``` Effects: May change state through POST /api/connections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### connections.revoke Revoke a P2P connection. Contract: DELETE /api/connections/{connectionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: connections:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "connectionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "connectionId": { "type": "string", "minLength": 1 } }, "required": [ "connectionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Revoke P2P connection.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/connections/{connectionId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### ledger.list List P2P ledger entries. Contract: GET /api/ledger Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: ledger:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List P2P ledger.", "additionalProperties": true } ``` Effects: Reads state through GET /api/ledger without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### settlements.preview Preview P2P settlement batches. Contract: POST /api/settlements/preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settlements:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buyer_org_id": { "type": "string", "minLength": 1 }, "seller_org_id": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Preview settlements.", "additionalProperties": true } ``` Effects: May change state through POST /api/settlements/preview. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### settlements.create Create a P2P settlement. Contract: POST /api/settlements/create Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settlements:approve Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "buyer_org_id": "00000000-0000-4000-8000-000000000000", "seller_org_id": "00000000-0000-4000-8000-000000000000", "currency": "USD" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "buyer_org_id": { "type": "string", "minLength": 1 }, "seller_org_id": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 1 }, "trigger": { "type": "string", "enum": [ "threshold", "schedule", "manual", "invoice", "delivery" ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Create settlement.", "additionalProperties": true } ``` Effects: May change state through POST /api/settlements/create. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### policies.get Get P2P policy. Contract: GET /api/policies Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: policy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Get P2P policy.", "additionalProperties": true } ``` Effects: Reads state through GET /api/policies without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### policies.update Update P2P policy. Contract: PUT /api/policies Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: policy:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "auto_approve_under_minor": 1, "agent_spend_limit_minor_per_day": 1, "human_approval_threshold_minor": 1 } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "auto_approve_under_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "agent_spend_limit_minor_per_day": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "human_approval_threshold_minor": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "unknown_counterparty_requires_approval": { "anyOf": [ { "type": "boolean" }, { "type": "number" }, { "type": "string" } ] }, "blocked_capability_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "string", "minLength": 1 } ] }, "trusted_counterparty_org_ids": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1 } }, { "type": "string", "minLength": 1 } ] } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Update P2P policy.", "additionalProperties": true } ``` Effects: May change state through PUT /api/policies. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### actions.list List P2P action requests. Contract: GET /api/actions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: actions:invoke Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "limit": 1, "state": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "limit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100 }, "state": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by List P2P actions.", "additionalProperties": true } ``` Effects: Reads state through GET /api/actions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### actions.get Get one organization-scoped P2P action request and its lifecycle details. Contract: GET /api/actions/{requestId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: actions:invoke Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "requestId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/actions/{requestId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### actions.request Request a P2P action. Contract: POST /api/actions/request Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: actions:request Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "capability_id": "00000000-0000-4000-8000-000000000000", "idempotency_key": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "capability_id": { "type": "string", "minLength": 1 }, "idempotency_key": { "type": "string", "minLength": 1 }, "inputs": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string", "minLength": 1 } ] } }, "required": [ "capability_id", "idempotency_key" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Request P2P action.", "additionalProperties": true } ``` Effects: May change state through POST /api/actions/request. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### actions.respond Respond to a P2P action. Contract: POST /api/actions/{requestId}/respond Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: actions:respond Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "requestId": "example", "response": "accepted" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "response": { "type": "string", "enum": [ "accepted", "quoted", "rejected", "approved" ] }, "quote": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string", "minLength": 1 } ] }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "requestId", "response" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Respond to P2P action.", "additionalProperties": true } ``` Effects: May change state through POST /api/actions/{requestId}/respond. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### actions.complete Complete a P2P action. Contract: POST /api/actions/{requestId}/complete Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: actions:respond Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "requestId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "result": { "anyOf": [ { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} }, { "type": "string", "minLength": 1 } ] } }, "required": [ "requestId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Complete P2P action.", "additionalProperties": true } ``` Effects: May change state through POST /api/actions/{requestId}/complete. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### actions.dispute Dispute a P2P action. Contract: POST /api/actions/{requestId}/dispute Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: actions:respond Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "requestId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "requestId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "requestId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Dispute P2P action.", "additionalProperties": true } ``` Effects: May change state through POST /api/actions/{requestId}/dispute. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### holds.release Resolve a P2P hold to the buyer or seller and apply any required ledger counter-reversal. Contract: POST /api/holds/{holdId}/release Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: actions:respond Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "holdId": "example", "resolution": "buyer" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "holdId": { "type": "string", "minLength": 1 }, "resolution": { "type": "string", "enum": [ "buyer", "seller" ] }, "reason": { "type": "string", "minLength": 1 } }, "required": [ "holdId", "resolution" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/holds/{holdId}/release. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### organizations.data.export Export the caller organization's P2P records across directory, runtime, ledger, and audit stores. Contract: GET /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "organizationId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 } }, "required": [ "organizationId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/{organizationId}/data without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Erase organization-owned P2P content while retaining immutable bilateral financial records required for ledger integrity. Contract: DELETE /api/organizations/{organizationId}/data Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "organizationId": "example", "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "organizationId": { "type": "string", "minLength": 1 }, "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "organizationId", "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/{organizationId}/data. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ## TopoloWeb source contract Human reference: https://docs.topolo.app/systems/topolo-web Machine reference: https://docs.topolo.app/machine/systems/topolo-web.json Source revisions: apps/TopoloWeb@30bfa2a69264ff4adb674121bac9ed20f407bf6b Deploy targets: 3; implemented actions: 44; declared actions: 44; uncatalogued served routes: 0; mobile contracts: 1; route signals: 5. ### organizations.data.export Export all TopoloWeb workspaces, sites, content, submissions, agent activity, operational records, and uploaded-asset metadata owned by the authenticated organization without preview, domain-verification, or client-address credentials. Contract: GET /api/organizations/data/export Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/organizations/data/export without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### organizations.data.erase Permanently erase all TopoloWeb data owned by the authenticated organization across control, content, events and agent databases plus published KV objects while retaining backups under policy. Contract: DELETE /api/organizations/data/erase Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: privacy:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "confirmation": "ERASE" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "confirmation": { "type": "string", "const": "ERASE" } }, "required": [ "confirmation" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/organizations/data/erase. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### workspaces.delete Permanently delete an empty, non-default TopoloWeb workspace. Contract: DELETE /api/workspaces/{workspaceId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: workspace:delete Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "workspaceId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "workspaceId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "workspaceId": { "type": "string", "minLength": 1 } }, "required": [ "ok", "workspaceId" ], "additionalProperties": false } ``` Effects: Confirms the TopoloWeb workspace is empty, then asks Topolo Auth to archive its canonical identity. Verification: Call app_topolo_auth.workspaces.list and confirm the archived workspace id is absent. Recovery: 409 workspace_delete_blocked: Remove owned sites or select another default workspace, then retry the deletion. ### forms.submissions.create Call POST /forms/{formId}/submissions. Contract: POST /api/forms/{formId}/submissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: none declared Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "formId": "example", "siteId": "example", "pageId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "formId": { "type": "string", "minLength": 1 }, "siteId": { "type": "string", "minLength": 1 }, "pageId": { "type": "string", "minLength": 1 }, "turnstileToken": { "type": "string", "minLength": 1 }, "cf-turnstile-response": { "type": "string", "minLength": 1 } }, "required": [ "formId", "siteId", "pageId" ], "additionalProperties": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" } ] } } ``` Output schema: ```json { "type": "object", "description": "Response returned by Forms Submissions Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/forms/{formId}/submissions. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.create Call POST /studio/sites. Contract: POST /api/studio/sites Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "intent": { "type": "string", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "minLength": 1 }, "offer": { "type": "string", "minLength": 1 }, "tone": { "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "differentiators": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string", "minLength": 1 } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.build Create a TopoloWeb site from a full canonical SiteContent payload and optionally publish it. This is the agent-safe Topolo Developers action path for Codex, Claude, CLI, and MCP site builds. Contract: POST /api/studio/sites/build Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "site": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" }, "content": { "intent": "business_site", "siteTitle": "example", "siteDescription": "example", "contactEmail": "user@example.com", "navigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "footerNavigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "menus": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "placement": "custom", "items": [] } ], "styleClasses": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "targetKind": "container", "targetScope": "section", "style": { "backgroundColor": "example", "backgroundImageUrl": "https://example.com", "backgroundMode": "cover" } } ], "theme": { "primary": "example", "secondary": "example", "surface": "example", "ink": "example", "muted": "example", "accent": "example", "accentSoft": "example", "glow": "example", "headingFont": "example", "bodyFont": "example", "radius": "example" }, "document": { "version": 1, "pages": [] }, "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [] } ], "codeSnippets": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "slot": "head", "code": "example", "enabled": true } ] } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Build TopoloWeb site", "type": "object", "description": "Create a site from complete canonical content and optionally publish it.", "properties": { "site": { "$ref": "#/$defs/createSite" }, "content": { "$ref": "#/$defs/siteContent" }, "publish": { "type": "boolean", "description": "Publish the first immutable version after quality validation." }, "publishLabel": { "type": "string", "description": "Optional first-version label.", "minLength": 1 } }, "required": [ "site", "content" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "New site state, quality evidence, preview coordinates, and optional first published version.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } }, "version": { "description": "First published version when publish=true; omitted otherwise.", "anyOf": [ { "$ref": "#/$defs/siteVersion" }, { "type": "null" } ] }, "urls": { "$ref": "#/$defs/siteUrls" } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions", "urls" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Effects: Creates one site and draft content. Publishes only when publish=true. Verification: Open urls.previewUrl at every required viewport. When published, open urls.publicUrl and confirm the intended version. Recovery: 400 invalid_site_payload: Correct the payload using sites.capabilities.get, then call sites.validate. 422 publish_blocked: Resolve every error in qualityReport before publishing. ### sites.capabilities.get Get the canonical repository-independent site schema, block catalog, examples, viewports, and workflow. Contract: GET /api/studio/sites/capabilities Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "TopoloWeb clean-room agent capabilities and canonical schemas.", "properties": { "contractVersion": { "type": "string", "description": "Version of the public agent contract.", "minLength": 1 }, "docsUrl": { "type": "string", "description": "Public operational documentation URL.", "format": "uri" }, "siteContentSchema": { "type": "object", "description": "Canonical SiteContent JSON Schema.", "additionalProperties": true }, "buildInputSchema": { "type": "object", "description": "sites.build input JSON Schema.", "additionalProperties": true }, "blockCatalog": { "type": "array", "description": "Renderer-backed block catalog with fields and design capabilities.", "items": { "type": "object", "description": "One block capability entry.", "additionalProperties": true } }, "compositionRecipes": { "type": "array", "description": "Audience-specific composition plans that use the block catalog deliberately.", "items": { "type": "object", "description": "One complete composition recipe.", "properties": { "id": { "type": "string", "description": "Stable recipe identifier.", "enum": [ "angel-investor", "marketplace-developer", "partner-channel", "platform-pitch", "venture-investor" ] }, "title": { "type": "string", "description": "Human-readable recipe title.", "minLength": 1 }, "audience": { "type": "string", "description": "Audience the composition is designed to persuade.", "minLength": 1 }, "visualThesis": { "type": "string", "description": "Unifying visual direction for the site.", "minLength": 1 }, "contentPlan": { "type": "array", "description": "Ordered content and block plan.", "items": { "type": "object", "description": "One block choice and its narrative job.", "properties": { "purpose": { "type": "string", "description": "Narrative purpose of the block.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "itemsPlacement": { "type": "string", "description": "Optional repeated-item placement.", "enum": [ "left", "right" ] }, "note": { "type": "string", "description": "Implementation guidance for this block.", "minLength": 1 } }, "required": [ "purpose", "kind", "note" ], "additionalProperties": false } }, "interactionThesis": { "type": "array", "description": "Interaction and reading-flow principles.", "items": { "type": "string", "description": "One interaction principle.", "minLength": 1 } }, "avoid": { "type": "array", "description": "Composition failure modes to avoid.", "items": { "type": "string", "description": "One failure mode.", "minLength": 1 } } }, "required": [ "id", "title", "audience", "visualThesis", "contentPlan", "interactionThesis", "avoid" ], "additionalProperties": false } }, "viewports": { "type": "array", "description": "Required responsive QA viewports.", "items": { "type": "object", "description": "One required QA viewport.", "properties": { "id": { "type": "string", "description": "Viewport identifier.", "enum": [ "mobile", "tablet", "desktop", "4k" ] }, "width": { "type": "integer", "description": "Viewport width in CSS pixels.", "minimum": 1 }, "description": { "type": "string", "description": "What this viewport verifies.", "minLength": 1 } }, "required": [ "id", "width", "description" ], "additionalProperties": false } }, "workflow": { "type": "array", "description": "Ordered clean-room build workflow.", "items": { "type": "string", "description": "One workflow step.", "minLength": 1 } }, "examples": { "type": "array", "description": "Canonical generated examples for every supported site intent.", "items": { "type": "object", "description": "One named intent example.", "properties": { "id": { "type": "string", "description": "Stable example identifier.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "content": { "$ref": "#/$defs/siteContent" } }, "required": [ "id", "intent", "content" ], "additionalProperties": false } } }, "required": [ "contractVersion", "docsUrl", "siteContentSchema", "buildInputSchema", "blockCatalog", "compositionRecipes", "viewports", "workflow", "examples" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Effects: Reads state through GET /api/studio/sites/capabilities without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.validate Validate complete site content and return deterministic quality findings without persisting changes. Contract: POST /api/studio/sites/validate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "site": { "name": "example", "businessType": "example", "audience": "example", "offer": "example", "tone": "example" }, "content": { "intent": "business_site", "siteTitle": "example", "siteDescription": "example", "contactEmail": "user@example.com", "navigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "footerNavigation": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "href": "example", "kind": "primary" } ], "menus": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "placement": "custom", "items": [] } ], "styleClasses": [ { "id": "00000000-0000-4000-8000-000000000000", "name": "example", "targetKind": "container", "targetScope": "section", "style": { "backgroundColor": "example", "backgroundImageUrl": "https://example.com", "backgroundMode": "cover" } } ], "theme": { "primary": "example", "secondary": "example", "surface": "example", "ink": "example", "muted": "example", "accent": "example", "accentSoft": "example", "glow": "example", "headingFont": "example", "bodyFont": "example", "radius": "example" }, "document": { "version": 1, "pages": [] }, "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [] } ], "codeSnippets": [ { "id": "00000000-0000-4000-8000-000000000000", "label": "example", "slot": "head", "code": "example", "enabled": true } ] } } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Validate TopoloWeb site", "type": "object", "description": "Validate a complete canonical site payload without persisting it.", "properties": { "site": { "$ref": "#/$defs/createSite" }, "content": { "$ref": "#/$defs/siteContent" } }, "required": [ "site", "content" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Non-persisting TopoloWeb validation result.", "properties": { "valid": { "type": "boolean", "description": "Whether the payload is structurally valid and has no blocking quality issues." }, "qualityReport": { "$ref": "#/$defs/qualityReport" } }, "required": [ "valid", "qualityReport" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Effects: Reads state through POST /api/studio/sites/validate without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.bootstrap Get the site list and selected site for the active workspace. Contract: GET /api/studio/sites/bootstrap Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "site_id": "00000000-0000-4000-8000-000000000000" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "site_id": { "type": "string", "minLength": 1 } }, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/bootstrap without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.update Call PUT /studio/sites/{siteId}. Contract: PUT /api/studio/sites/{siteId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "brief": { "type": "object", "properties": { "intent": { "type": "string", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessName": { "type": "string", "minLength": 1 }, "businessType": { "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "minLength": 1 }, "offer": { "type": "string", "minLength": 1 }, "tone": { "type": "string", "minLength": 1 }, "differentiators": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "theme": { "type": "object", "properties": { "primary": { "type": "string", "minLength": 1 }, "secondary": { "type": "string", "minLength": 1 }, "surface": { "type": "string", "minLength": 1 }, "ink": { "type": "string", "minLength": 1 }, "muted": { "type": "string", "minLength": 1 }, "accent": { "type": "string", "minLength": 1 }, "accentSoft": { "type": "string", "minLength": 1 }, "glow": { "type": "string", "minLength": 1 }, "headingFont": { "type": "string", "minLength": 1 }, "bodyFont": { "type": "string", "minLength": 1 }, "radius": { "type": "string", "minLength": 1 }, "brandLogoUrl": { "type": "string" }, "brandLogoAlt": { "type": "string" }, "brandLogoWidth": { "type": "string" }, "brandLogoHeight": { "type": "string" }, "pageDefaults": { "type": "object", "properties": { "sectionPaddingTop": { "type": "number", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "minimum": 0 }, "sectionMarginTop": { "type": "number" }, "sectionMarginBottom": { "type": "number" }, "sectionMarginLeft": { "type": "number" }, "sectionMarginRight": { "type": "number" }, "headingSize": { "type": "number", "minimum": 1 }, "headingLineHeight": { "type": "number", "minimum": 0.5 }, "bodySize": { "type": "number", "minimum": 1 }, "bodyLineHeight": { "type": "number", "minimum": 0.5 }, "cardPadding": { "type": "number", "minimum": 0 }, "layoutGap": { "type": "number", "minimum": 0 }, "responsive": { "type": "object", "propertyNames": { "type": "string", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "type": "object", "properties": { "sectionPaddingTop": { "type": "number", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "minimum": 0 }, "sectionMarginTop": { "type": "number" }, "sectionMarginBottom": { "type": "number" }, "sectionMarginLeft": { "type": "number" }, "sectionMarginRight": { "type": "number" }, "headingSize": { "type": "number", "minimum": 1 }, "headingLineHeight": { "type": "number", "minimum": 0.5 }, "bodySize": { "type": "number", "minimum": 1 }, "bodyLineHeight": { "type": "number", "minimum": 0.5 }, "cardPadding": { "type": "number", "minimum": 0 }, "layoutGap": { "type": "number", "minimum": 0 } }, "additionalProperties": false } } }, "additionalProperties": false }, "customCss": { "type": "string" } }, "additionalProperties": false }, "navigation": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false } }, "footerNavigation": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false } }, "menus": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "placement": { "type": "string", "const": "custom" }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false } }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "meta": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "badge": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" }, "imageUrl": { "type": "string" }, "alt": { "type": "string" } }, "required": [ "id", "title", "body" ], "additionalProperties": false } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false } }, "styleClasses": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "targetKind": { "type": "string", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "const": "section" }, "style": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "backgroundImageUrl": { "type": "string" }, "backgroundMode": { "type": "string", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number" }, "paddingBottom": { "type": "number" }, "paddingBlockLinked": { "type": "boolean" }, "paddingLeft": { "type": "number" }, "paddingRight": { "type": "number" }, "paddingInlineLinked": { "type": "boolean" }, "marginTop": { "type": "number" }, "marginBottom": { "type": "number" }, "marginBlockLinked": { "type": "boolean" }, "marginLeft": { "type": "number" }, "marginRight": { "type": "number" }, "marginInlineLinked": { "type": "boolean" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "borderRadius": { "type": "number" }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" }, "cardPadding": { "type": "number" }, "columnCount": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 }, { "type": "number", "const": 4 } ] }, "columnSpans": { "type": "array", "items": { "type": "number" } }, "layoutGap": { "type": "number" }, "nestedSectionPadding": { "type": "number" }, "mediaAspectRatio": { "type": "string", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number" }, "mediaFocalY": { "type": "number" }, "dividerTop": { "type": "boolean" }, "dividerBottom": { "type": "boolean" }, "dividerThickness": { "type": "number" }, "dividerWidth": { "type": "number" }, "dividerLineStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string" }, "responsive": { "type": "object", "propertyNames": { "type": "string", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "type": "object", "properties": { "backgroundColor": { "type": "string" }, "backgroundImageUrl": { "type": "string" }, "backgroundMode": { "type": "string", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number" }, "paddingBottom": { "type": "number" }, "paddingBlockLinked": { "type": "boolean" }, "paddingLeft": { "type": "number" }, "paddingRight": { "type": "number" }, "paddingInlineLinked": { "type": "boolean" }, "marginTop": { "type": "number" }, "marginBottom": { "type": "number" }, "marginBlockLinked": { "type": "boolean" }, "marginLeft": { "type": "number" }, "marginRight": { "type": "number" }, "marginInlineLinked": { "type": "boolean" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "borderRadius": { "type": "number" }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" }, "cardPadding": { "type": "number" }, "columnCount": { "anyOf": [ { "type": "number", "const": 2 }, { "type": "number", "const": 3 }, { "type": "number", "const": 4 } ] }, "columnSpans": { "type": "array", "items": { "type": "number" } }, "layoutGap": { "type": "number" }, "nestedSectionPadding": { "type": "number" }, "mediaAspectRatio": { "type": "string", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number" }, "mediaFocalY": { "type": "number" }, "dividerTop": { "type": "boolean" }, "dividerBottom": { "type": "boolean" }, "dividerThickness": { "type": "number" }, "dividerWidth": { "type": "number" }, "dividerLineStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1 }, "targetKind": { "type": "string", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "const": "item" }, "style": { "type": "object", "properties": { "padding": { "type": "number" }, "radius": { "type": "number" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "imageFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number" }, "imageFocalY": { "type": "number" }, "textPadding": { "type": "number" }, "textRadius": { "type": "number" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" }, "responsive": { "type": "object", "propertyNames": { "type": "string", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "type": "object", "properties": { "padding": { "type": "number" }, "radius": { "type": "number" }, "borderWidth": { "type": "number" }, "borderStyle": { "type": "string", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string" }, "imageFit": { "type": "string", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number" }, "imageFocalY": { "type": "number" }, "textPadding": { "type": "number" }, "textRadius": { "type": "number" }, "textAlign": { "type": "string", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number" }, "headingLineHeight": { "type": "number" }, "bodySize": { "type": "number" }, "bodyLineHeight": { "type": "number" } }, "additionalProperties": false } } }, "additionalProperties": false } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] } }, "codeSnippets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "slot": { "type": "string", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string" }, "enabled": { "type": "boolean" } }, "required": [ "label", "slot", "code" ], "additionalProperties": false } }, "seo": { "type": "object", "properties": { "titleTemplate": { "type": "string", "minLength": 1 }, "metaTitle": { "type": "string", "minLength": 1 }, "metaDescription": { "type": "string", "minLength": 1 }, "faviconUrl": { "type": "string", "minLength": 1 }, "openGraphImageUrl": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 } }, "additionalProperties": false }, "announcementBar": { "anyOf": [ { "type": "object", "properties": { "enabled": { "type": "boolean" }, "text": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 } }, "required": [ "enabled", "text" ], "additionalProperties": false }, { "type": "null" } ] }, "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/studio/sites/{siteId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.unpublish Remove the active published version from one site. Contract: POST /api/studio/sites/{siteId}/unpublish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/unpublish. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.archive Archive one site. Contract: POST /api/studio/sites/{siteId}/archive Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/archive. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.delete Permanently delete one site and its owned content. Contract: DELETE /api/studio/sites/{siteId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/studio/sites/{siteId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.collections.update Call PUT /studio/sites/{siteId}/collections. Contract: PUT /api/studio/sites/{siteId}/collections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "collections": [ { "id": "00000000-0000-4000-8000-000000000000", "slug": "example", "kind": "apps", "label": "example", "items": [ { "id": "00000000-0000-4000-8000-000000000000", "title": "example", "body": "example" } ] } ] } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "collections": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "minLength": 1 }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 }, "body": { "type": "string" }, "meta": { "type": "string", "minLength": 1 }, "value": { "type": "string", "minLength": 1 }, "badge": { "type": "string", "minLength": 1 }, "href": { "type": "string", "minLength": 1 }, "targetBlank": { "type": "boolean" }, "imageUrl": { "type": "string" }, "alt": { "type": "string" } }, "required": [ "id", "title", "body" ], "additionalProperties": false } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false } } }, "required": [ "siteId", "collections" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Collections Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/studio/sites/{siteId}/collections. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.collections.import Import a CSV into one site collection and persist the import result. Contract: POST /api/studio/sites/{siteId}/collections/import Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "slug": "example", "kind": "apps", "label": "example", "csv": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "id": { "type": "string", "minLength": 1 }, "slug": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "minLength": 1 }, "csv": { "type": "string", "minLength": 1, "maxLength": 1048576 } }, "required": [ "siteId", "slug", "kind", "label", "csv" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/collections/import. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.code_snippets.create Call POST /studio/sites/{siteId}/code-snippets. Contract: POST /api/studio/sites/{siteId}/code-snippets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "label": "example", "slot": "head", "code": "example", "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "slot": { "type": "string", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "siteId": { "type": "string", "minLength": 1 } }, "required": [ "label", "slot", "code", "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Code Snippets Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/code-snippets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.code_snippets.update Call PUT /studio/sites/{siteId}/code-snippets/{snippetId}. Contract: PUT /api/studio/sites/{siteId}/code-snippets/{snippetId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "label": "example", "slot": "head", "code": "example", "siteId": "example", "snippetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "label": { "type": "string", "minLength": 1 }, "slot": { "type": "string", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string" }, "enabled": { "type": "boolean" }, "siteId": { "type": "string", "minLength": 1 }, "snippetId": { "type": "string", "minLength": 1 } }, "required": [ "label", "slot", "code", "siteId", "snippetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Code Snippets Update.", "additionalProperties": true } ``` Effects: May change state through PUT /api/studio/sites/{siteId}/code-snippets/{snippetId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.code_snippets.delete Call DELETE /studio/sites/{siteId}/code-snippets/{snippetId}. Contract: DELETE /api/studio/sites/{siteId}/code-snippets/{snippetId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "siteId": "example", "snippetId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "snippetId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "snippetId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Code Snippets Delete.", "additionalProperties": true } ``` Effects: May change state through DELETE /api/studio/sites/{siteId}/code-snippets/{snippetId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.agent_sessions.create Call POST /studio/sites/{siteId}/agent/sessions. Contract: POST /api/studio/sites/{siteId}/agent/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "title": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Agent Sessions Create.", "additionalProperties": true } ``` Effects: Creates one reviewable editing session without changing site content. Verification: Call app_topolo_web.sites.agent_sessions.get with the returned session.id. Recovery: 401 authentication_required: Authenticate again with Topolo Auth, then retry once. 403 permission_denied: Use a credential with studio:write for the selected workspace. 404 site_not_found: List sites in the selected workspace and retry with a returned site id. ### sites.agent_sessions.messages.create Call POST /studio/sites/{siteId}/agent/sessions/{sessionId}/messages. Contract: POST /api/studio/sites/{siteId}/agent/sessions/{sessionId}/messages Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "sessionId": "example", "content": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 }, "content": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId", "content" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Agent Sessions Messages Create.", "additionalProperties": true } ``` Effects: Adds one user instruction and creates a pending, reviewable site proposal. Verification: Call app_topolo_web.sites.agent_sessions.get and confirm the returned pending proposal matches the instruction. Recovery: 503 dependency_unavailable: Keep the current session, wait for the proposal dependency to recover, then send a new instruction once. ### sites.agent_sessions.proposals.apply Call POST /studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/apply. Contract: POST /api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/apply Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "sessionId": "example", "proposalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 }, "proposalId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId", "proposalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Agent Sessions Proposals Apply.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/apply. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.agent_sessions.proposals.reject Call POST /studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/reject. Contract: POST /api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/reject Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "siteId": "example", "sessionId": "example", "proposalId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 }, "proposalId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId", "proposalId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Agent Sessions Proposals Reject.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/agent/sessions/{sessionId}/proposals/{proposalId}/reject. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.generate Call POST /studio/sites/{siteId}/generate. Contract: POST /api/studio/sites/{siteId}/generate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "intent": { "type": "string", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessName": { "type": "string", "minLength": 1 }, "businessType": { "type": "string", "minLength": 1 }, "location": { "type": "string", "minLength": 1 }, "audience": { "type": "string", "minLength": 1 }, "offer": { "type": "string", "minLength": 1 }, "tone": { "type": "string", "minLength": 1 }, "differentiators": { "type": "array", "items": { "type": "string" } }, "goals": { "type": "array", "items": { "type": "string" } }, "prompt": { "type": "string", "minLength": 1 }, "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Generate.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/generate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.document_nodes.regenerate Call POST /studio/sites/{siteId}/document/nodes/{nodeId}/regenerate. Contract: POST /api/studio/sites/{siteId}/document/nodes/{nodeId}/regenerate Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "nodeId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "nodeId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "nodeId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Document Nodes Regenerate.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/document/nodes/{nodeId}/regenerate. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.publish Call POST /studio/sites/{siteId}/publish. Contract: POST /api/studio/sites/{siteId}/publish Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: publish:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "site_example", "label": "Launch" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Publish TopoloWeb site", "type": "object", "description": "Publish one quality-approved site as a new immutable active version.", "properties": { "siteId": { "type": "string", "description": "Site identifier returned by sites.build or site discovery.", "minLength": 1 }, "label": { "type": "string", "description": "Optional human-readable version label.", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Published site, immutable version, quality evidence, and verification URLs.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "version": { "$ref": "#/$defs/siteVersion" }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "urls": { "$ref": "#/$defs/siteUrls" } }, "required": [ "site", "version", "qualityReport", "urls" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Effects: Creates and activates one immutable published version. Verification: Open urls.publicUrl and confirm the returned version.id is active. Recovery: 422 publish_blocked: Resolve every error returned by sites.publish.preflight. ### sites.domains.create Call POST /studio/sites/{siteId}/domains. Contract: POST /api/studio/sites/{siteId}/domains Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: domains:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "hostname": "example", "kind": "platform" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "hostname": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "platform", "custom" ] }, "isPrimary": { "type": "boolean" } }, "required": [ "siteId", "hostname", "kind" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Domains Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/domains. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.domains.verify Call POST /studio/sites/{siteId}/domains/{domainId}/verify. Contract: POST /api/studio/sites/{siteId}/domains/{domainId}/verify Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: domains:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "domainId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "domainId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "domainId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Domains Verify.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/domains/{domainId}/verify. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.domains.delete Delete one domain from a site. Contract: DELETE /api/studio/sites/{siteId}/domains/{domainId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: domains:write Agent access: confirm; read-only: false; destructive: true; confirmation: true Example input: ```json { "siteId": "example", "domainId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "domainId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "domainId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through DELETE /api/studio/sites/{siteId}/domains/{domainId}. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.assets.create Call POST /studio/sites/{siteId}/assets. Contract: POST /api/studio/sites/{siteId}/assets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "label": "example", "kind": "favicon", "url": "https://example.com", "alt": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "favicon", "logo", "hero", "gallery", "proof", "poster", "video" ] }, "url": { "type": "string", "minLength": 1 }, "alt": { "type": "string" } }, "required": [ "siteId", "label", "kind", "url", "alt" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Assets Create.", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/assets. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### sites.assets.upload Upload a base64-encoded image or video asset to one site. Contract: POST /api/studio/sites/{siteId}/assets/upload Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: assets:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "example", "label": "example", "kind": "favicon", "fileName": "example", "contentType": "example", "dataBase64": "example", "alt": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "label": { "type": "string", "minLength": 1 }, "kind": { "type": "string", "enum": [ "favicon", "logo", "hero", "gallery", "proof", "poster", "video" ] }, "fileName": { "type": "string", "minLength": 1 }, "contentType": { "type": "string", "minLength": 1 }, "dataBase64": { "type": "string", "minLength": 1 }, "alt": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "label", "kind", "fileName", "contentType", "dataBase64", "alt" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: May change state through POST /api/studio/sites/{siteId}/assets/upload. Inspect the plan and honor the published confirmation policy. Verification: Check the structured action result. Read the affected resource back through the corresponding get or list action. Recovery: Do not retry an ambiguous mutation until a read confirms whether it applied. Use a published inverse, update, archive, or delete action only after inspecting its contract. ### widget.get Get the TopoloOne widget summary for this service. Contract: GET /api/widget Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: runtime:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/widget without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.list Call GET /studio/sites. Contract: GET /api/studio/sites Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json {} ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.get Call GET /studio/sites/{siteId}. Contract: GET /api/studio/sites/{siteId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.quality.get Get deterministic content and launch-quality findings for one site. Contract: GET /api/studio/sites/{siteId}/quality Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "$ref": "#/$defs/qualityReport", "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/quality without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.preview.get Get stable draft-preview and public URLs plus required responsive QA viewports. Contract: GET /api/studio/sites/{siteId}/preview Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Stable draft preview coordinates.", "properties": { "siteId": { "type": "string", "description": "Site identifier.", "minLength": 1 }, "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public URL used after publication.", "format": "uri" }, "viewports": { "type": "array", "description": "Required responsive QA viewports.", "items": { "type": "object", "description": "One required QA viewport.", "properties": { "id": { "type": "string", "description": "Viewport identifier.", "enum": [ "mobile", "tablet", "desktop", "4k" ] }, "width": { "type": "integer", "description": "Viewport width in CSS pixels.", "minimum": 1 }, "description": { "type": "string", "description": "What this viewport verifies.", "minLength": 1 } }, "required": [ "id", "width", "description" ], "additionalProperties": false } } }, "required": [ "siteId", "previewUrl", "publicUrl", "viewports" ], "additionalProperties": false } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/preview without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.publish.preflight Check publish readiness, verification URLs, responsive viewports, and rollback action without changing the site. Contract: GET /api/studio/sites/{siteId}/publish-preflight Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Non-mutating publish readiness result.", "properties": { "canPublish": { "type": "boolean", "description": "Whether deterministic launch gates allow publishing." }, "siteId": { "type": "string", "description": "Site identifier.", "minLength": 1 }, "previewUrl": { "type": "string", "description": "Draft preview URL to verify visually.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public URL that publishing will activate.", "format": "uri" }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "requiredViewports": { "type": "array", "description": "Viewport widths that must be visually verified.", "items": { "type": "integer", "description": "Viewport width in CSS pixels.", "minimum": 1 } }, "rollbackActionId": { "type": "string", "description": "Action used to restore a previous published version.", "const": "app_topolo_web.sites.versions.restore" } }, "required": [ "canPublish", "siteId", "previewUrl", "publicUrl", "qualityReport", "requiredViewports", "rollbackActionId" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/publish-preflight without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.collections.list Call GET /studio/sites/{siteId}/collections. Contract: GET /api/studio/sites/{siteId}/collections Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Collections List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/collections without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.code_snippets.list Call GET /studio/sites/{siteId}/code-snippets. Contract: GET /api/studio/sites/{siteId}/code-snippets Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Code Snippets List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/code-snippets without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.agent_sessions.list Call GET /studio/sites/{siteId}/agent/sessions. Contract: GET /api/studio/sites/{siteId}/agent/sessions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Agent Sessions List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/agent/sessions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.agent_sessions.get Call GET /studio/sites/{siteId}/agent/sessions/{sessionId}. Contract: GET /api/studio/sites/{siteId}/agent/sessions/{sessionId} Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example", "sessionId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 }, "sessionId": { "type": "string", "minLength": 1 } }, "required": [ "siteId", "sessionId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Agent Sessions Get.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/agent/sessions/{sessionId} without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.versions.list Call GET /studio/sites/{siteId}/versions. Contract: GET /api/studio/sites/{siteId}/versions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Versions List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/versions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.versions.restore Restore and publish one saved site version. Contract: POST /api/studio/sites/{siteId}/versions/{versionId}/restore Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: publish:write Agent access: confirm; read-only: false; destructive: false; confirmation: true Example input: ```json { "siteId": "site_example", "versionId": "version_example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "Restore TopoloWeb site version", "type": "object", "description": "Restore one immutable version belonging to the selected site and activate it as a new version.", "properties": { "siteId": { "type": "string", "description": "Site identifier returned by site discovery.", "minLength": 1 }, "versionId": { "type": "string", "description": "Version identifier returned by sites.versions.list for the same site.", "minLength": 1 } }, "required": [ "siteId", "versionId" ], "additionalProperties": false } ``` Output schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "Published site, immutable version, quality evidence, and verification URLs.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "version": { "$ref": "#/$defs/siteVersion" }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "urls": { "$ref": "#/$defs/siteUrls" } }, "required": [ "site", "version", "qualityReport", "urls" ], "additionalProperties": false, "$defs": { "jsonValue": { "description": "A JSON-compatible component property value.", "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "null" }, { "type": "array", "items": { "$ref": "#/$defs/jsonValue" } }, { "type": "object", "additionalProperties": { "$ref": "#/$defs/jsonValue" } } ] }, "actionLink": { "type": "object", "description": "A rendered call-to-action link.", "properties": { "label": { "type": "string", "description": "Visible link label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, mailto, tel, or HTTPS URL.", "minLength": 1 }, "linkKind": { "type": "string", "description": "Whether the link targets a TopoloWeb page or a custom URL.", "enum": [ "custom", "page" ] }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "label", "href" ], "additionalProperties": false }, "navigationItem": { "type": "object", "description": "One site navigation entry.", "properties": { "id": { "type": "string", "description": "Stable navigation item identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Visible navigation label.", "minLength": 1 }, "href": { "type": "string", "description": "Root-relative path, anchor, or external URL.", "minLength": 1 }, "kind": { "type": "string", "description": "Navigation emphasis.", "enum": [ "primary", "secondary", "cta" ] }, "parentId": { "type": "string", "description": "Optional parent item identifier for one-level menus." }, "targetBlank": { "type": "boolean", "description": "Open the link in a new browser tab." } }, "required": [ "id", "label", "href", "kind" ], "additionalProperties": false }, "navigationMenu": { "type": "object", "description": "A named reusable navigation menu.", "properties": { "id": { "type": "string", "description": "Stable menu identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable menu name.", "minLength": 1 }, "placement": { "type": "string", "description": "Custom menu placement marker.", "const": "custom" }, "items": { "type": "array", "description": "Ordered menu entries.", "items": { "$ref": "#/$defs/navigationItem" } } }, "required": [ "id", "name", "placement", "items" ], "additionalProperties": false }, "pageStyleDefaultsBase": { "type": "object", "description": "Site-wide default layout and typography values.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 } }, "additionalProperties": false }, "pageStyleDefaults": { "type": "object", "description": "Desktop page defaults with optional viewport overrides.", "properties": { "sectionPaddingTop": { "type": "number", "description": "Default section top padding in pixels.", "minimum": 0 }, "sectionPaddingBottom": { "type": "number", "description": "Default section bottom padding in pixels.", "minimum": 0 }, "sectionPaddingLeft": { "type": "number", "description": "Default section left padding in pixels.", "minimum": 0 }, "sectionPaddingRight": { "type": "number", "description": "Default section right padding in pixels.", "minimum": 0 }, "sectionMarginTop": { "type": "number", "description": "Default section top margin in pixels." }, "sectionMarginBottom": { "type": "number", "description": "Default section bottom margin in pixels." }, "sectionMarginLeft": { "type": "number", "description": "Default section left margin in pixels." }, "sectionMarginRight": { "type": "number", "description": "Default section right margin in pixels." }, "headingSize": { "type": "number", "description": "Default heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Default heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Default body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Default body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Default card padding in pixels.", "minimum": 0 }, "layoutGap": { "type": "number", "description": "Default layout gap in pixels.", "minimum": 0 }, "responsive": { "type": "object", "description": "Viewport-specific page-default overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/pageStyleDefaultsBase" } } }, "additionalProperties": false }, "theme": { "type": "object", "description": "Complete TopoloWeb theme and responsive page defaults.", "properties": { "primary": { "type": "string", "description": "Primary brand color.", "minLength": 1 }, "secondary": { "type": "string", "description": "Secondary brand color.", "minLength": 1 }, "surface": { "type": "string", "description": "Primary surface color.", "minLength": 1 }, "ink": { "type": "string", "description": "Primary text color.", "minLength": 1 }, "muted": { "type": "string", "description": "Muted text color.", "minLength": 1 }, "accent": { "type": "string", "description": "Accent color.", "minLength": 1 }, "accentSoft": { "type": "string", "description": "Soft accent surface color.", "minLength": 1 }, "glow": { "type": "string", "description": "Decorative glow color.", "minLength": 1 }, "headingFont": { "type": "string", "description": "CSS heading font stack.", "minLength": 1 }, "bodyFont": { "type": "string", "description": "CSS body font stack.", "minLength": 1 }, "radius": { "type": "string", "description": "Default CSS corner radius.", "minLength": 1 }, "brandLogoUrl": { "type": "string", "description": "HTTPS brand-logo URL." }, "brandLogoAlt": { "type": "string", "description": "Accessible brand-logo description." }, "brandLogoWidth": { "type": "string", "description": "CSS brand-logo width." }, "brandLogoHeight": { "type": "string", "description": "CSS brand-logo height." }, "pageDefaults": { "$ref": "#/$defs/pageStyleDefaults" }, "customCss": { "type": "string", "description": "Reviewed site-wide CSS loaded after generated styles." } }, "required": [ "primary", "secondary", "surface", "ink", "muted", "accent", "accentSoft", "glow", "headingFont", "bodyFont", "radius" ], "additionalProperties": false }, "sectionStyleBase": { "type": "object", "description": "Desktop section style values.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." } }, "additionalProperties": false }, "sectionStyle": { "type": "object", "description": "Section style values with optional responsive overrides.", "properties": { "backgroundColor": { "type": "string", "description": "CSS background color." }, "backgroundImageUrl": { "type": "string", "description": "HTTPS background image URL." }, "backgroundMode": { "type": "string", "description": "Background image sizing mode.", "enum": [ "cover", "contain", "stretch", "tile" ] }, "backgroundPosition": { "type": "string", "description": "Background image position.", "enum": [ "center", "top", "bottom", "left", "right", "top left", "top right", "bottom left", "bottom right" ] }, "textColor": { "type": "string", "description": "CSS foreground color." }, "textAlign": { "type": "string", "description": "Text alignment.", "enum": [ "left", "center", "right" ] }, "imagePlacement": { "type": "string", "description": "Media placement relative to text.", "enum": [ "left", "right" ] }, "itemsPlacement": { "type": "string", "description": "Repeated items placement relative to section copy for supported compositions.", "enum": [ "left", "right" ] }, "paddingTop": { "type": "number", "description": "Top padding in pixels.", "minimum": 0 }, "paddingBottom": { "type": "number", "description": "Bottom padding in pixels.", "minimum": 0 }, "paddingBlockLinked": { "type": "boolean", "description": "Whether top and bottom padding should stay linked." }, "paddingLeft": { "type": "number", "description": "Left padding in pixels.", "minimum": 0 }, "paddingRight": { "type": "number", "description": "Right padding in pixels.", "minimum": 0 }, "paddingInlineLinked": { "type": "boolean", "description": "Whether left and right padding should stay linked." }, "marginTop": { "type": "number", "description": "Top margin in pixels." }, "marginBottom": { "type": "number", "description": "Bottom margin in pixels." }, "marginBlockLinked": { "type": "boolean", "description": "Whether top and bottom margins should stay linked." }, "marginLeft": { "type": "number", "description": "Left margin in pixels." }, "marginRight": { "type": "number", "description": "Right margin in pixels." }, "marginInlineLinked": { "type": "boolean", "description": "Whether left and right margins should stay linked." }, "borderWidth": { "type": "number", "description": "Border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Border line style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "CSS border color." }, "borderRadius": { "type": "number", "description": "Corner radius in pixels.", "minimum": 0 }, "headingSize": { "type": "number", "description": "Heading font size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Body font size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Body line-height multiplier.", "minimum": 0.5 }, "cardPadding": { "type": "number", "description": "Repeated-card padding in pixels.", "minimum": 0 }, "columnCount": { "type": "number", "description": "Responsive column count.", "enum": [ 2, 3, 4 ] }, "columnSpans": { "type": "array", "description": "Grid spans for explicit columns.", "items": { "type": "number", "description": "One column span.", "minimum": 1 } }, "layoutGap": { "type": "number", "description": "Gap between layout children in pixels.", "minimum": 0 }, "nestedSectionPadding": { "type": "number", "description": "Padding around nested sections in pixels.", "minimum": 0 }, "mediaAspectRatio": { "type": "string", "description": "Media aspect ratio.", "enum": [ "16 / 9", "4 / 3", "1 / 1", "9 / 16" ] }, "mediaFit": { "type": "string", "description": "Media object-fit behavior.", "enum": [ "cover", "contain", "fill", "none" ] }, "mediaFocalX": { "type": "number", "description": "Horizontal focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "mediaFocalY": { "type": "number", "description": "Vertical focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "dividerTop": { "type": "boolean", "description": "Whether a top divider is rendered." }, "dividerBottom": { "type": "boolean", "description": "Whether a bottom divider is rendered." }, "dividerThickness": { "type": "number", "description": "Divider thickness in pixels.", "minimum": 0 }, "dividerWidth": { "type": "number", "description": "Divider width percentage.", "minimum": 0, "maximum": 100 }, "dividerLineStyle": { "type": "string", "description": "Divider line style.", "enum": [ "solid", "dashed", "dotted" ] }, "customCss": { "type": "string", "description": "Reviewed CSS declarations scoped to this section." }, "responsive": { "type": "object", "description": "Viewport-specific section-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionStyleBase" } } }, "additionalProperties": false }, "sectionItemStyleBase": { "type": "object", "description": "Desktop repeated-item style values.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 } }, "additionalProperties": false }, "sectionItemStyle": { "type": "object", "description": "Repeated-item style values with optional responsive overrides.", "properties": { "padding": { "type": "number", "description": "Item padding in pixels.", "minimum": 0 }, "radius": { "type": "number", "description": "Item corner radius in pixels.", "minimum": 0 }, "borderWidth": { "type": "number", "description": "Item border width in pixels.", "minimum": 0 }, "borderStyle": { "type": "string", "description": "Item border style.", "enum": [ "solid", "dashed", "dotted" ] }, "borderColor": { "type": "string", "description": "Item border color." }, "imageFit": { "type": "string", "description": "Item image fit.", "enum": [ "cover", "contain", "fill", "none" ] }, "imageFocalX": { "type": "number", "description": "Horizontal image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "imageFocalY": { "type": "number", "description": "Vertical image focal point from 0 to 100.", "minimum": 0, "maximum": 100 }, "textPadding": { "type": "number", "description": "Text-panel padding in pixels.", "minimum": 0 }, "textRadius": { "type": "number", "description": "Text-panel corner radius in pixels.", "minimum": 0 }, "textAlign": { "type": "string", "description": "Item text alignment.", "enum": [ "left", "center", "right" ] }, "headingSize": { "type": "number", "description": "Item heading size in pixels.", "minimum": 1 }, "headingLineHeight": { "type": "number", "description": "Item heading line-height multiplier.", "minimum": 0.5 }, "bodySize": { "type": "number", "description": "Item body size in pixels.", "minimum": 1 }, "bodyLineHeight": { "type": "number", "description": "Item body line-height multiplier.", "minimum": 0.5 }, "responsive": { "type": "object", "description": "Viewport-specific item-style overrides.", "propertyNames": { "type": "string", "description": "A non-desktop responsive override breakpoint.", "enum": [ "4k", "tablet", "mobile" ] }, "additionalProperties": { "$ref": "#/$defs/sectionItemStyleBase" } } }, "additionalProperties": false }, "sectionItem": { "type": "object", "description": "One repeated card, row, quote, metric, question, or media item.", "properties": { "id": { "type": "string", "description": "Stable item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title." }, "body": { "type": "string", "description": "Visible supporting copy." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional value or price." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." }, "style": { "$ref": "#/$defs/sectionItemStyle" }, "styleClassIds": { "type": "array", "description": "Reusable item style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "sectionValue": { "type": "object", "description": "Renderer-backed block content without persisted child arrays.", "properties": { "id": { "type": "string", "description": "Stable section identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "eyebrow": { "type": "string", "description": "Optional eyebrow copy." }, "title": { "type": "string", "description": "Visible section heading." }, "body": { "type": "string", "description": "Visible section body copy." }, "kicker": { "type": "string", "description": "Optional supporting kicker." }, "primaryAction": { "$ref": "#/$defs/actionLink" }, "secondaryAction": { "$ref": "#/$defs/actionLink" }, "imageUrl": { "type": "string", "description": "Optional section image URL." }, "alt": { "type": "string", "description": "Accessible section-image description." }, "presentation": { "type": "string", "description": "A renderer-backed composition designed for the selected block type.", "enum": [ "annotated", "cards", "columns", "divided", "editorial", "manifesto", "mosaic", "poster", "ruled", "split", "spotlight", "tiers", "timeline" ] }, "styleClassIds": { "type": "array", "description": "Reusable section style-class identifiers.", "items": { "type": "string", "description": "One style-class identifier.", "minLength": 1 } }, "style": { "$ref": "#/$defs/sectionStyle" }, "formId": { "type": "string", "description": "Form identifier for a contact-form block." }, "collectionSlug": { "type": "string", "description": "Collection slug bound to this block." }, "collectionLimit": { "type": "number", "description": "Maximum collection entries rendered.", "minimum": 1 }, "collectionSort": { "type": "string", "description": "Collection sorting behavior.", "enum": [ "manual", "title_asc", "title_desc", "meta_asc", "meta_desc" ] }, "html": { "type": "string", "description": "Reviewed HTML for embed-capable blocks." }, "videoUrl": { "type": "string", "description": "Direct, YouTube, or Vimeo video URL." }, "videoProvider": { "type": "string", "description": "Video provider.", "enum": [ "direct", "youtube", "vimeo" ] }, "videoPosterUrl": { "type": "string", "description": "Video poster image URL." }, "videoAutoplay": { "type": "boolean", "description": "Autoplay video when allowed." }, "videoControls": { "type": "boolean", "description": "Show native video controls." }, "videoMuted": { "type": "boolean", "description": "Mute video playback." }, "componentName": { "type": "string", "description": "Approved custom component name." }, "componentProps": { "type": "object", "description": "Component-specific reviewed JSON properties.", "additionalProperties": { "$ref": "#/$defs/jsonValue" } }, "menuId": { "type": "string", "description": "Reusable menu identifier bound to a menu block." } }, "required": [ "id", "kind", "title", "body" ], "additionalProperties": false }, "pageValue": { "type": "object", "description": "Persisted page metadata.", "properties": { "id": { "type": "string", "description": "Stable page identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Root-relative page slug beginning with /.", "pattern": "^/" }, "title": { "type": "string", "description": "Visible page heading and title-template input.", "minLength": 1 }, "description": { "type": "string", "description": "Page search and social description." } }, "required": [ "id", "slug", "title", "description" ], "additionalProperties": false }, "columnValue": { "type": "object", "description": "Persisted layout-column metadata.", "properties": { "id": { "type": "string", "description": "Stable column identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Optional editor label." }, "span": { "type": "number", "description": "Grid span.", "minimum": 1 }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id" ], "additionalProperties": false }, "source": { "type": "object", "description": "Original product-domain identity for a document node.", "properties": { "kind": { "type": "string", "description": "Source record kind.", "enum": [ "page", "section", "column", "item" ] }, "id": { "type": "string", "description": "Source record identifier.", "minLength": 1 } }, "required": [ "kind", "id" ], "additionalProperties": false }, "pageNode": { "type": "object", "description": "A canonical page node owning exactly one page-body slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "page" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Parent node identifier when nested." }, "source": { "$ref": "#/$defs/source" }, "value": { "$ref": "#/$defs/pageValue" }, "children": { "type": "array", "description": "Exactly one page-body slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "value", "children" ], "additionalProperties": false }, "slotNode": { "type": "object", "description": "A canonical child slot controlling accepted node kinds.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "slot" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning page, layout, or block node identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "slotKind": { "type": "string", "description": "Child-slot role.", "enum": [ "page-body", "layout-column", "block-items" ] }, "accepts": { "type": "array", "description": "Document node kinds allowed in this slot.", "items": { "type": "string", "description": "One allowed node kind.", "enum": [ "layout", "block", "item" ] } }, "parentSectionId": { "type": "string", "description": "Owning section identifier for layout and block slots." }, "columnId": { "type": "string", "description": "Column identifier for layout-column slots." }, "value": { "$ref": "#/$defs/columnValue" }, "children": { "type": "array", "description": "Canonical child nodes.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "slotKind", "accepts", "children" ], "additionalProperties": false }, "layoutNode": { "type": "object", "description": "A canonical layout block owning one or more layout-column slots.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "layout" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "layoutKind": { "type": "string", "description": "Layout behavior.", "enum": [ "container", "grid", "stack", "flex-row", "columns" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Layout-column slots.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "layoutKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "blockNode": { "type": "object", "description": "A canonical renderer block with optional block-items slot.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "block" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "blockKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "sectionId": { "type": "string", "description": "Persisted section identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionValue" }, "children": { "type": "array", "description": "Optional block-items slot.", "items": { "$ref": "#/$defs/siteDocumentNode" } } }, "required": [ "id", "kind", "pageId", "label", "path", "source", "blockKind", "sectionKind", "sectionId", "value", "children" ], "additionalProperties": false }, "itemNode": { "type": "object", "description": "A canonical repeated-item leaf node.", "properties": { "id": { "type": "string", "description": "Stable document node identifier.", "minLength": 1 }, "kind": { "type": "string", "description": "Document node kind.", "const": "item" }, "pageId": { "type": "string", "description": "Owning page identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable editor label.", "minLength": 1 }, "path": { "type": "array", "description": "Stable document-tree path segments.", "items": { "type": "string", "description": "One path segment.", "minLength": 1 } }, "parentNodeId": { "type": "string", "description": "Owning block-items slot identifier.", "minLength": 1 }, "source": { "$ref": "#/$defs/source" }, "parentSectionId": { "type": "string", "description": "Owning block section identifier.", "minLength": 1 }, "itemId": { "type": "string", "description": "Persisted item identifier.", "minLength": 1 }, "value": { "$ref": "#/$defs/sectionItem" }, "children": { "type": "array", "description": "Item nodes are leaves and must have no children.", "maxItems": 0 } }, "required": [ "id", "kind", "pageId", "label", "path", "parentNodeId", "source", "parentSectionId", "itemId", "value", "children" ], "additionalProperties": false }, "siteDocumentNode": { "description": "One canonical TopoloWeb document node.", "oneOf": [ { "$ref": "#/$defs/pageNode" }, { "$ref": "#/$defs/slotNode" }, { "$ref": "#/$defs/layoutNode" }, { "$ref": "#/$defs/blockNode" }, { "$ref": "#/$defs/itemNode" } ] }, "siteDocument": { "type": "object", "description": "Canonical versioned TopoloWeb document tree.", "properties": { "version": { "type": "integer", "description": "Document schema version.", "const": 1 }, "pages": { "type": "array", "description": "Canonical page nodes.", "items": { "$ref": "#/$defs/pageNode" } } }, "required": [ "version", "pages" ], "additionalProperties": false }, "styleClass": { "description": "A reusable section or item style class.", "oneOf": [ { "type": "object", "description": "Reusable section style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "section" }, "style": { "$ref": "#/$defs/sectionStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false }, { "type": "object", "description": "Reusable repeated-item style class.", "properties": { "id": { "type": "string", "description": "Stable style-class identifier.", "minLength": 1 }, "name": { "type": "string", "description": "Human-readable class name.", "minLength": 1 }, "targetKind": { "type": "string", "description": "The renderer-backed TopoloWeb block kind.", "enum": [ "container", "layout-grid", "stack", "flex-row", "spacer", "hero", "feature-grid", "story", "proof", "header", "announcement", "menu", "columns", "accordion", "faq", "cta", "contact-form", "image", "gallery", "video", "logo-cloud", "stats", "testimonials", "pricing", "comparison-table", "app-grid", "article-list", "legal", "embed", "custom-component", "divider", "footer" ] }, "targetScope": { "type": "string", "description": "Style-class target scope.", "const": "item" }, "style": { "$ref": "#/$defs/sectionItemStyle" } }, "required": [ "id", "name", "targetKind", "targetScope", "style" ], "additionalProperties": false } ] }, "collectionItem": { "type": "object", "description": "One reusable CMS collection entry.", "properties": { "id": { "type": "string", "description": "Stable collection-item identifier.", "minLength": 1 }, "title": { "type": "string", "description": "Visible item title.", "minLength": 1 }, "body": { "type": "string", "description": "Visible item body." }, "meta": { "type": "string", "description": "Optional metadata." }, "value": { "type": "string", "description": "Optional price or value." }, "badge": { "type": "string", "description": "Optional badge label." }, "href": { "type": "string", "description": "Optional item link." }, "targetBlank": { "type": "boolean", "description": "Open the item link in a new tab." }, "imageUrl": { "type": "string", "description": "Optional item image URL." }, "alt": { "type": "string", "description": "Accessible item-image description." } }, "required": [ "id", "title", "body" ], "additionalProperties": false }, "collection": { "type": "object", "description": "Reusable CMS collection.", "properties": { "id": { "type": "string", "description": "Stable collection identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Stable collection slug.", "minLength": 1 }, "kind": { "type": "string", "description": "Collection content kind.", "enum": [ "apps", "pricing", "articles", "changelog", "legal", "faq", "custom" ] }, "label": { "type": "string", "description": "Human-readable collection label.", "minLength": 1 }, "items": { "type": "array", "description": "Ordered collection entries.", "items": { "$ref": "#/$defs/collectionItem" } } }, "required": [ "id", "slug", "kind", "label", "items" ], "additionalProperties": false }, "codeSnippet": { "type": "object", "description": "Reviewed bounded code injection.", "properties": { "id": { "type": "string", "description": "Stable snippet identifier.", "minLength": 1 }, "label": { "type": "string", "description": "Human-readable snippet label.", "minLength": 1 }, "slot": { "type": "string", "description": "Injection slot.", "enum": [ "head", "body_start", "body_end" ] }, "code": { "type": "string", "description": "Reviewed HTML, CSS, or JavaScript source." }, "enabled": { "type": "boolean", "description": "Whether this snippet is active." } }, "required": [ "id", "label", "slot", "code", "enabled" ], "additionalProperties": false }, "seo": { "type": "object", "description": "Site-wide search and social metadata defaults.", "properties": { "titleTemplate": { "type": "string", "description": "Title template; %s is replaced by the page title." }, "metaTitle": { "type": "string", "description": "Default page title override." }, "metaDescription": { "type": "string", "description": "Default search and social description." }, "faviconUrl": { "type": "string", "description": "Browser and bookmark icon URL." }, "openGraphImageUrl": { "type": "string", "description": "Default Open Graph image URL." }, "canonicalUrl": { "type": "string", "description": "Canonical site URL." } }, "additionalProperties": false }, "siteContent": { "type": "object", "description": "Complete canonical TopoloWeb site content.", "properties": { "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "siteTitle": { "type": "string", "description": "Public site title.", "minLength": 1 }, "siteDescription": { "type": "string", "description": "Public site description." }, "contactEmail": { "type": "string", "description": "Public contact email.", "minLength": 1 }, "contactPhone": { "type": "string", "description": "Optional public contact phone number." }, "navigation": { "type": "array", "description": "Primary site navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "footerNavigation": { "type": "array", "description": "Footer navigation.", "items": { "$ref": "#/$defs/navigationItem" } }, "menus": { "type": "array", "description": "Reusable custom menus.", "items": { "$ref": "#/$defs/navigationMenu" } }, "styleClasses": { "type": "array", "description": "Reusable section and item styles.", "items": { "$ref": "#/$defs/styleClass" } }, "theme": { "$ref": "#/$defs/theme" }, "document": { "$ref": "#/$defs/siteDocument" }, "collections": { "type": "array", "description": "Reusable CMS collections.", "items": { "$ref": "#/$defs/collection" } }, "codeSnippets": { "type": "array", "description": "Reviewed bounded code snippets.", "items": { "$ref": "#/$defs/codeSnippet" } }, "seo": { "$ref": "#/$defs/seo" } }, "required": [ "intent", "siteTitle", "siteDescription", "contactEmail", "navigation", "footerNavigation", "menus", "styleClasses", "theme", "document", "collections", "codeSnippets" ], "additionalProperties": false }, "createSite": { "type": "object", "description": "Brief used to create a new TopoloWeb site.", "properties": { "name": { "type": "string", "description": "Internal and initial public site name.", "minLength": 1 }, "intent": { "type": "string", "description": "The kind of website being created.", "enum": [ "business_site", "landing_page", "portfolio", "agency", "product_suite" ] }, "businessType": { "type": "string", "description": "Business or project category.", "minLength": 1 }, "audience": { "type": "string", "description": "Primary intended audience.", "minLength": 1 }, "offer": { "type": "string", "description": "Primary product, service, or proposition.", "minLength": 1 }, "tone": { "type": "string", "description": "Desired writing and visual tone.", "minLength": 1 }, "location": { "type": "string", "description": "Optional geographic market." }, "differentiators": { "type": "array", "description": "Specific differentiators to communicate.", "items": { "type": "string", "description": "One differentiator." } }, "goals": { "type": "array", "description": "Desired user and business outcomes.", "items": { "type": "string", "description": "One goal." } }, "prompt": { "type": "string", "description": "Additional generation direction." } }, "required": [ "name", "businessType", "audience", "offer", "tone" ], "additionalProperties": false }, "qualityIssue": { "type": "object", "description": "One actionable launch-quality finding.", "properties": { "id": { "type": "string", "description": "Stable issue code.", "minLength": 1 }, "severity": { "type": "string", "description": "Issue severity.", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "description": "Short issue title.", "minLength": 1 }, "detail": { "type": "string", "description": "Actionable remediation detail.", "minLength": 1 } }, "required": [ "id", "severity", "title", "detail" ], "additionalProperties": false }, "qualityReport": { "type": "object", "description": "Deterministic content and launch-quality report.", "properties": { "generatedAt": { "type": "string", "description": "ISO-8601 generation timestamp.", "format": "date-time" }, "score": { "type": "number", "description": "Quality score from 0 to 100.", "minimum": 0, "maximum": 100 }, "issues": { "type": "array", "description": "Actionable quality findings.", "items": { "$ref": "#/$defs/qualityIssue" } } }, "required": [ "generatedAt", "score", "issues" ], "additionalProperties": false }, "siteRecord": { "type": "object", "description": "One TopoloWeb site and its current editable content.", "properties": { "id": { "type": "string", "description": "Stable site identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "slug": { "type": "string", "description": "Platform hostname slug.", "minLength": 1 }, "name": { "type": "string", "description": "Internal site name.", "minLength": 1 }, "status": { "type": "string", "description": "Current lifecycle status.", "enum": [ "draft", "published", "archived" ] }, "brief": { "type": "object", "description": "Generation brief retained for iterative edits.", "additionalProperties": true }, "draftContent": { "$ref": "#/$defs/siteContent" }, "currentVersionId": { "type": "string", "description": "Currently published immutable version identifier." }, "draftPreviewToken": { "type": "string", "description": "Opaque token used by the draft preview URL.", "minLength": 1 }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "slug", "name", "status", "brief", "draftContent", "draftPreviewToken", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteVersion": { "type": "object", "description": "One immutable published site version.", "properties": { "id": { "type": "string", "description": "Stable version identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "versionNumber": { "type": "integer", "description": "Monotonic site version number.", "minimum": 1 }, "label": { "type": "string", "description": "Human-readable version label.", "minLength": 1 }, "snapshot": { "$ref": "#/$defs/siteContent" }, "previewToken": { "type": "string", "description": "Opaque immutable-version preview token.", "minLength": 1 }, "publishedAt": { "type": "string", "description": "ISO-8601 publication timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "versionNumber", "label", "snapshot", "previewToken", "publishedAt" ], "additionalProperties": false }, "siteDomain": { "type": "object", "description": "One platform or custom site domain.", "properties": { "id": { "type": "string", "description": "Stable domain identifier.", "minLength": 1 }, "organizationId": { "type": "string", "description": "Owning Topolo organization identifier.", "minLength": 1 }, "workspaceId": { "type": "string", "description": "Owning Topolo workspace identifier.", "minLength": 1 }, "siteId": { "type": "string", "description": "Parent site identifier.", "minLength": 1 }, "hostname": { "type": "string", "description": "Domain hostname without scheme.", "minLength": 1 }, "kind": { "type": "string", "description": "Domain ownership kind.", "enum": [ "platform", "custom" ] }, "status": { "type": "string", "description": "DNS and TLS activation status.", "enum": [ "pending_dns", "pending_ssl", "active", "failed" ] }, "dnsTarget": { "type": "string", "description": "DNS target required for this domain.", "minLength": 1 }, "verificationToken": { "type": "string", "description": "Opaque DNS ownership verification token.", "minLength": 1 }, "isPrimary": { "type": "boolean", "description": "Whether this is the primary public hostname." }, "createdAt": { "type": "string", "description": "ISO-8601 creation timestamp.", "format": "date-time" }, "updatedAt": { "type": "string", "description": "ISO-8601 last-update timestamp.", "format": "date-time" } }, "required": [ "id", "organizationId", "workspaceId", "siteId", "hostname", "kind", "status", "dnsTarget", "verificationToken", "isPrimary", "createdAt", "updatedAt" ], "additionalProperties": false }, "siteUrls": { "type": "object", "description": "Stable URLs used to preview and verify the site.", "properties": { "previewUrl": { "type": "string", "description": "Authenticated draft-preview URL.", "format": "uri" }, "publicUrl": { "type": "string", "description": "Primary public site URL.", "format": "uri" } }, "required": [ "previewUrl", "publicUrl" ], "additionalProperties": false }, "siteDetails": { "type": "object", "description": "Complete editable site state returned after a build.", "properties": { "site": { "$ref": "#/$defs/siteRecord" }, "versions": { "type": "array", "description": "Published immutable versions, newest first.", "items": { "$ref": "#/$defs/siteVersion" } }, "domains": { "type": "array", "description": "Platform and custom domains.", "items": { "$ref": "#/$defs/siteDomain" } }, "assets": { "type": "array", "description": "Uploaded or linked site assets.", "items": { "type": "object", "description": "One site asset record.", "additionalProperties": true } }, "submissions": { "type": "array", "description": "Recent form submissions.", "items": { "type": "object", "description": "One site form submission.", "additionalProperties": true } }, "events": { "type": "array", "description": "Recent site lifecycle events.", "items": { "type": "object", "description": "One site event.", "additionalProperties": true } }, "insights": { "type": "object", "description": "Derived site activity counters.", "additionalProperties": true }, "qualityReport": { "$ref": "#/$defs/qualityReport" }, "agentSessions": { "type": "array", "description": "Agent editing sessions.", "items": { "type": "object", "description": "One agent session summary.", "additionalProperties": true } } }, "required": [ "site", "versions", "domains", "assets", "submissions", "events", "insights", "qualityReport", "agentSessions" ], "additionalProperties": false } } } ``` Effects: Creates and activates a new immutable version from the selected snapshot. Verification: Open urls.publicUrl and confirm version.id is the new active version. Recovery: 404 version_not_found: Call sites.versions.list and select a version belonging to the same site. ### sites.domains.list Call GET /studio/sites/{siteId}/domains. Contract: GET /api/studio/sites/{siteId}/domains Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: settings:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "description": "Response returned by Sites Domains List.", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/domains without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read. ### sites.submissions.list List form submissions captured by one site. Contract: GET /api/studio/sites/{siteId}/submissions Implementation: implemented. Matched to a served route extracted from canonical staging source. Permission: studio:read Agent access: auto; read-only: true; destructive: false; confirmation: false Example input: ```json { "siteId": "example" } ``` Input schema: ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "siteId": { "type": "string", "minLength": 1 } }, "required": [ "siteId" ], "additionalProperties": false } ``` Output schema: ```json { "type": "object", "additionalProperties": true } ``` Effects: Reads state through GET /api/studio/sites/{siteId}/submissions without a declared mutation. Verification: Check the structured action result and pagination or resource identifiers before using it downstream. Recovery: Correct identity, resource context, permission, or input validation failures, then retry the read.