platform · active
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.
Documentation map
- Topolo Auth — Public overview of identity, service registration, API keys, and permission ownership across the platform.
- Application Catalog — Platform-wide inventory of the Topolo application portfolio and where each product currently stands in docs coverage.
- TopoloLearn — Public overview of the Topolo-native multi-brand learning platform for branded education businesses, cohort delivery, assessment, and certification.
- Topolo Nexus — Public overview of Nexus as the platform gateway for metered provider and application usage across Topolo applications.
- Agents and Automation — Clean-room operating guide for Codex, Claude, and headless automation using Topolo OAuth or API keys.
- Authentication — How authentication and authorization flow through Topolo Auth and downstream services.
- Introduction — Overview of the Topolo documentation platform, what is considered canonical, and where to start.
- Quick Start — Fast onboarding path for developers integrating with Topolo services.
- Third-Party Auth Integration — Canonical guide for external developers integrating with Topolo Auth without relying on first-party repo docs.
- Partner Program — How agencies, dev shops, resellers, MSPs, and ISVs build, sell, and earn on the Topolo platform.
- API Keys — Central API key model, scope ownership, and resource binding behavior across Topolo services.
- Platform Architecture — Top-level platform shape, authority boundaries, and how the unified documentation platform maps onto the codebase.
- Topolo 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.
Authority and runtime
- System ID
topolo-platform- App IDs
- none
- Owners
- platform
- Repositories
- topolo-platform/core/TopoloAuth, topolo-platform/core/TopoloCloudControl, system-apps/TopoloDocs, topolo-platform/services/TopoloLocalize, topolo-platform/packages/topolo-ui-kit
- Hosts
- https://docs.topolo.app
- Dependencies
- topolo-auth, topolo-one
Security and data ownership
- Risk tier
- critical
- Tenant isolation
- mixed
- Privacy classification
- restricted
- Storage
- d1, durable_object, external_provider, kv, r2
- Export and deletion
- planned
- Enterprise ready
- no
Source-derived capability inventory
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
Declared actions: 232 · API routes: 122 · UI routes: 25
{
"id": "topolo-platform",
"name": "Topolo Platform",
"slug": "topolo-platform",
"kind": "platform",
"visibility": "public",
"repo_paths": [
"topolo-platform/core/TopoloAuth",
"topolo-platform/core/TopoloCloudControl",
"system-apps/TopoloDocs",
"topolo-platform/services/TopoloLocalize",
"topolo-platform/packages/topolo-ui-kit"
],
"source_revisions": [
{
"source_path": "topolo-platform/core/TopoloAuth",
"repository": "topolo-platform",
"revision": "515376de81efed9734741b2a1d691c8195243073",
"ref": "origin/staging"
},
{
"source_path": "topolo-platform/core/TopoloCloudControl",
"repository": "topolo-platform",
"revision": "515376de81efed9734741b2a1d691c8195243073",
"ref": "origin/staging"
},
{
"source_path": "system-apps/TopoloDocs",
"repository": "system-apps/TopoloDocs",
"revision": "content-sha256:f1156f3f8bfa67eea5ea769c2e21502bf7883b145bf30212f0ea11cc6a2b1140",
"ref": "working-tree"
},
{
"source_path": "topolo-platform/services/TopoloLocalize",
"repository": "topolo-platform",
"revision": "515376de81efed9734741b2a1d691c8195243073",
"ref": "origin/staging"
},
{
"source_path": "topolo-platform/packages/topolo-ui-kit",
"repository": "topolo-platform",
"revision": "515376de81efed9734741b2a1d691c8195243073",
"ref": "origin/staging"
}
],
"source_counts": {
"source_files": 660,
"test_files": 415,
"test_cases": 0,
"migration_files": 69,
"database_tables": 0,
"manifests": 4,
"deploy_targets": 5,
"actions": 232,
"mobile_contracts": 1,
"notifications": 32,
"package_manifests": 7,
"deployment_configs": 1
},
"manifests": [
{
"source_path": "topolo-platform/core/TopoloAuth/topolo.app.json",
"service_slug": "topolo-platform",
"name": "topolo-auth",
"app_id": "app_topolo_auth",
"compatibility_date": "2026-04-10",
"primary_target": "api",
"environments": [
"development",
"production",
"staging"
],
"targets": [
{
"name": "api",
"kind": "worker",
"directory": ".",
"main": "src/index.js",
"worker_name": "topolo-auth",
"subdomain": "auth",
"healthcheck_path": "/health",
"variable_names": [],
"secret_names": [],
"bindings": [
{
"kind": "secretsStore",
"binding": "PLATFORM_AT_REST_MASTER_ENCRYPTION_KEY_STORE",
"target": null
},
{
"kind": "secretsStore",
"binding": "PLATFORM_AT_REST_MASTER_ENCRYPTION_KEY_PREVIOUS_STORE",
"target": null
}
]
}
],
"notifications": [
"auth.account.locked",
"auth.api_key.created",
"auth.api_key.expiring",
"auth.api_key.revoked",
"auth.email.verification_requested",
"auth.magic_link.requested",
"auth.mfa.changed",
"auth.passkey.added",
"auth.passkey.removed",
"auth.password.changed",
"auth.password.reset_requested",
"auth.session.new_device_signin",
"org.member.accepted",
"org.member.invited",
"org.member.removed",
"org.member.role_changed",
"org.service_access.approved",
"org.service_access.denied",
"org.service_access.requested",
"platform.account.deletion_completed",
"platform.account.deletion_requested",
"platform.welcome"
],
"notification_contract": {
"source_path": "topolo.notification-contracts.json",
"role": "producer",
"schema_version": 1,
"owner_app_id": "app_topolo_auth",
"events": [
{
"type": "auth.account.locked",
"version": 1,
"description": "Auth locked an account after the durable failed-login threshold was reached.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"locked_until",
"failed_attempts",
"ip_address"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"locked_until": {
"type": "string",
"format": "date-time"
},
"failed_attempts": {
"type": "integer"
},
"ip_address": {
"type": "string"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth locked an account after the durable failed-login threshold was reached.",
"body": "Open Topolo to review this security event.",
"object_type": "user_account",
"object_id": "usr_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"locked_until": "2026-07-20T00:15:00.000Z",
"failed_attempts": 5,
"ip_address": "203.0.113.1"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:account-locked:"
},
"sensitiveFields": [
"ip_address"
]
},
{
"type": "auth.api_key.created",
"version": 1,
"description": "Auth durably created an organization API key.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"api_key_id",
"api_key_name",
"app_id",
"expires_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"api_key_id": {
"type": "string",
"minLength": 1
},
"api_key_name": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"expires_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
]
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably created an organization API key.",
"body": "Open Topolo to review this security event.",
"object_type": "api_key",
"object_id": "key_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"api_key_id": "key_123",
"api_key_name": "Automation",
"app_id": "app_topolo_agent",
"expires_at": "2026-10-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:api-key-created:"
},
"sensitiveFields": []
},
{
"type": "auth.api_key.expiring",
"version": 1,
"description": "An active Auth API key entered its seven-day expiry window.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"api_key_id",
"api_key_name",
"app_id",
"expires_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"api_key_id": {
"type": "string",
"minLength": 1
},
"api_key_name": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"expires_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "An active Auth API key entered its seven-day expiry window.",
"body": "Open Topolo to review this security event.",
"object_type": "api_key",
"object_id": "key_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"api_key_id": "key_123",
"api_key_name": "Automation",
"app_id": "app_topolo_agent",
"expires_at": "2026-07-27T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:api-key-expiring:"
},
"sensitiveFields": []
},
{
"type": "auth.api_key.revoked",
"version": 1,
"description": "Auth durably revoked an organization API key.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"api_key_id",
"api_key_name",
"app_id",
"revoked_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"api_key_id": {
"type": "string",
"minLength": 1
},
"api_key_name": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"revoked_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably revoked an organization API key.",
"body": "Open Topolo to review this security event.",
"object_type": "api_key",
"object_id": "key_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"api_key_id": "key_123",
"api_key_name": "Automation",
"app_id": "app_topolo_agent",
"revoked_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:api-key-revoked:"
},
"sensitiveFields": []
},
{
"type": "auth.email.verification_requested",
"version": 1,
"description": "Auth persisted a single-use recovery-email verification token and requested delivery.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"verification_url",
"token_ttl_seconds",
"recipient_email"
],
"properties": {
"verification_url": {
"type": "string",
"format": "uri"
},
"token_ttl_seconds": {
"type": "integer",
"minimum": 1
},
"recipient_email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true
},
"examples": [
{
"verification_url": "https://auth.topolo.app/recovery-email/verify?token=token",
"token_ttl_seconds": 86400,
"recipient_email": "user@example.com"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"external"
],
"externalAddress": "required"
},
"idempotency": {
"required": true,
"pattern": "^auth:email-verification-requested:"
},
"sensitiveFields": [
"verification_url",
"recipient_email"
]
},
{
"type": "auth.magic_link.requested",
"version": 1,
"description": "Auth persisted a single-use magic-login token and requested delivery.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"magic_link_url",
"token_ttl_seconds",
"recipient_email"
],
"properties": {
"magic_link_url": {
"type": "string",
"format": "uri"
},
"token_ttl_seconds": {
"type": "integer",
"minimum": 1
},
"service_display_name": {
"type": "string"
},
"purpose": {
"enum": [
"signin",
"verify_email",
"owner_invite"
]
},
"recipient_email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true
},
"examples": [
{
"magic_link_url": "https://auth.topolo.app/magic-link/consume?token=token",
"token_ttl_seconds": 3600,
"service_display_name": "Topolo",
"purpose": "signin",
"recipient_email": "user@example.com"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"external"
],
"externalAddress": "required"
},
"idempotency": {
"required": true,
"pattern": "^auth:magic-link-requested:"
},
"sensitiveFields": [
"magic_link_url",
"recipient_email"
]
},
{
"type": "auth.mfa.changed",
"version": 1,
"description": "Auth durably changed the account multi-factor authentication state.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"enabled",
"changed_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"enabled": {
"type": "boolean"
},
"changed_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably changed the account multi-factor authentication state.",
"body": "Open Topolo to review this security event.",
"object_type": "user_security",
"object_id": "usr_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"enabled": true,
"changed_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:mfa-changed:"
},
"sensitiveFields": []
},
{
"type": "auth.passkey.added",
"version": 1,
"description": "Auth durably added a verified passkey credential.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"passkey_id",
"friendly_name",
"device_type",
"added_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"passkey_id": {
"type": "string",
"minLength": 1
},
"friendly_name": {
"type": "string",
"minLength": 1
},
"device_type": {
"type": "string",
"minLength": 1
},
"added_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably added a verified passkey credential.",
"body": "Open Topolo to review this security event.",
"object_type": "passkey",
"object_id": "pk_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"passkey_id": "pk_123",
"friendly_name": "MacBook Touch ID",
"device_type": "singleDevice",
"added_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:passkey-added:"
},
"sensitiveFields": []
},
{
"type": "auth.passkey.removed",
"version": 1,
"description": "Auth durably removed a passkey credential.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"passkey_id",
"friendly_name",
"device_type",
"removed_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"passkey_id": {
"type": "string",
"minLength": 1
},
"friendly_name": {
"type": "string"
},
"device_type": {
"type": "string"
},
"removed_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably removed a passkey credential.",
"body": "Open Topolo to review this security event.",
"object_type": "passkey",
"object_id": "pk_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"passkey_id": "pk_123",
"friendly_name": "MacBook Touch ID",
"device_type": "singleDevice",
"removed_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:passkey-removed:"
},
"sensitiveFields": []
},
{
"type": "auth.password.changed",
"version": 1,
"description": "Auth durably changed or reset an account password and revoked existing sessions.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"changed_at",
"reset_flow"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"changed_at": {
"type": "string",
"format": "date-time"
},
"reset_flow": {
"type": "boolean"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably changed or reset an account password and revoked existing sessions.",
"body": "Open Topolo to review this security event.",
"object_type": "user_security",
"object_id": "usr_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"changed_at": "2026-07-20T00:00:00.000Z",
"reset_flow": false
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:password-changed:"
},
"sensitiveFields": []
},
{
"type": "auth.password.reset_requested",
"version": 1,
"description": "Auth persisted a single-use password reset token and requested delivery.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"reset_url",
"token_ttl_seconds",
"recipient_email"
],
"properties": {
"reset_url": {
"type": "string",
"format": "uri"
},
"token_ttl_seconds": {
"type": "integer",
"minimum": 1
},
"recipient_email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true
},
"examples": [
{
"reset_url": "https://auth.topolo.app/password-reset?token=token",
"token_ttl_seconds": 3600,
"recipient_email": "user@example.com"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"external"
],
"externalAddress": "required"
},
"idempotency": {
"required": true,
"pattern": "^auth:password-reset-requested:"
},
"sensitiveFields": [
"reset_url",
"recipient_email"
]
},
{
"type": "auth.session.new_device_signin",
"version": 1,
"description": "Auth persisted a session for a previously unseen device fingerprint.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"device_label",
"ip_address",
"signed_in_at",
"reset_password_url"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"device_label": {
"type": "string",
"minLength": 1
},
"ip_address": {
"type": "string"
},
"approximate_location": {
"type": "string"
},
"timezone": {
"type": "string"
},
"signed_in_at": {
"type": "string",
"format": "date-time"
},
"reset_password_url": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth persisted a session for a previously unseen device fingerprint.",
"body": "Open Topolo to review this security event.",
"object_type": "session",
"object_id": "sess_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"device_label": "Safari on macOS",
"ip_address": "203.0.113.1",
"approximate_location": "Denpasar, Bali, ID",
"timezone": "Asia/Makassar",
"signed_in_at": "2026-07-20T00:00:00.000Z",
"reset_password_url": "https://auth.topolo.app/login?method=email#forgotPasswordLink"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:new-device-signin:"
},
"sensitiveFields": [
"ip_address",
"approximate_location"
]
},
{
"type": "org.member.accepted",
"version": 1,
"description": "Auth durably activated an organization membership.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"organization_display_name"
],
"properties": {
"organization_display_name": {
"type": "string",
"minLength": 1
},
"actor_display_name": {
"type": "string"
}
},
"additionalProperties": true
},
"examples": [
{
"organization_display_name": "Acme",
"actor_display_name": "Ada"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:member-accepted:"
},
"sensitiveFields": []
},
{
"type": "org.member.invited",
"version": 1,
"description": "Auth persisted an organization invitation and requested delivery.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"invite_url",
"invited_email",
"recipient_email",
"role",
"organization_display_name"
],
"properties": {
"invite_url": {
"type": "string",
"format": "uri"
},
"invited_email": {
"type": "string",
"format": "email"
},
"recipient_email": {
"type": "string",
"format": "email"
},
"role": {
"type": "string",
"minLength": 1
},
"organization_display_name": {
"type": "string",
"minLength": 1
},
"actor_display_name": {
"type": "string"
}
},
"additionalProperties": true
},
"examples": [
{
"invite_url": "https://auth.topolo.app/register?inviteCode=INVITE",
"invited_email": "invitee@example.com",
"recipient_email": "invitee@example.com",
"role": "member",
"organization_display_name": "Acme",
"actor_display_name": "Ada"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"external"
],
"externalAddress": "required"
},
"idempotency": {
"required": true,
"pattern": "^auth:member-invited:"
},
"sensitiveFields": [
"invite_url",
"invited_email",
"recipient_email"
]
},
{
"type": "org.member.removed",
"version": 1,
"description": "Auth durably ended an organization membership.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"organization_display_name",
"recipient_email",
"reason"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"organization_display_name": {
"type": "string",
"minLength": 1
},
"recipient_email": {
"type": "string",
"format": "email"
},
"reason": {
"type": "string"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably ended an organization membership.",
"body": "Open Topolo to review this security event.",
"object_type": "organization_member",
"object_id": "org_123:usr_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"organization_display_name": "Acme",
"recipient_email": "former.member@example.com",
"reason": "removed_by_organization_administrator"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"external"
],
"externalAddress": "required"
},
"idempotency": {
"required": true,
"pattern": "^auth:member-removed:"
},
"sensitiveFields": [
"recipient_email"
]
},
{
"type": "org.member.role_changed",
"version": 1,
"description": "Auth durably changed an organization member role.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"previous_role",
"role",
"changed_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"previous_role": {
"type": "string",
"minLength": 1
},
"role": {
"type": "string",
"minLength": 1
},
"changed_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably changed an organization member role.",
"body": "Open Topolo to review this security event.",
"object_type": "organization_member",
"object_id": "org_123:usr_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"previous_role": "member",
"role": "admin",
"changed_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:member-role-changed:"
},
"sensitiveFields": []
},
{
"type": "org.service_access.approved",
"version": 1,
"description": "Auth durably granted an application service to an organization.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"app_id",
"relationship_id",
"access_level",
"approved_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"app_id": {
"type": "string",
"minLength": 1
},
"relationship_id": {
"type": "string",
"minLength": 1
},
"access_level": {
"type": "string",
"minLength": 1
},
"approved_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably granted an application service to an organization.",
"body": "Open Topolo to review this security event.",
"object_type": "organization_service",
"object_id": "orgsvc_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"app_id": "app_topolo_agent",
"relationship_id": "orgsvc_123",
"access_level": "basic",
"approved_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:service-access-approved:"
},
"sensitiveFields": []
},
{
"type": "org.service_access.denied",
"version": 1,
"description": "Auth durably revoked an application service from an organization.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"app_id",
"relationship_id",
"denied_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"app_id": {
"type": "string",
"minLength": 1
},
"relationship_id": {
"type": "string",
"minLength": 1
},
"denied_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "Auth durably revoked an application service from an organization.",
"body": "Open Topolo to review this security event.",
"object_type": "organization_service",
"object_id": "orgsvc_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"app_id": "app_topolo_agent",
"relationship_id": "orgsvc_123",
"denied_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:service-access-denied:"
},
"sensitiveFields": []
},
{
"type": "org.service_access.requested",
"version": 1,
"description": "An organization member durably recorded a request for application access.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_type",
"object_id",
"occurred_at",
"surface",
"priority",
"category",
"severity",
"action_context",
"thread_key"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_type": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
},
"surface": {
"enum": [
"notification",
"action"
]
},
"priority": {
"enum": [
"low",
"normal",
"high",
"urgent"
]
},
"cta_url": {
"type": "string",
"format": "uri"
},
"cta_label": {
"type": "string"
},
"category": {
"type": "string"
},
"severity": {
"enum": [
"info",
"success",
"warning",
"critical"
]
},
"action_context": {
"type": "object"
},
"actor_display_name": {
"type": "string"
},
"thread_key": {
"type": "string"
}
},
"additionalProperties": true
},
"examples": [
{
"title": "An organization member durably recorded a request for application access.",
"body": "Open Topolo to review this security event.",
"object_type": "service_access_request",
"object_id": "org_123:app_topolo_agent:usr_123",
"occurred_at": "2026-07-20T00:00:00.000Z",
"surface": "notification",
"priority": "normal",
"cta_url": "https://admin.topolo.app/users/usr_123",
"cta_label": "Review access",
"category": "access",
"severity": "info",
"action_context": {
"organizationId": "org_123",
"appId": "app_topolo_agent"
},
"actor_display_name": "Ada",
"thread_key": "service-access-request:org_123:app_topolo_agent"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:service-access-request:"
},
"sensitiveFields": []
},
{
"type": "platform.account.deletion_completed",
"version": 1,
"description": "Auth permanently deleted the account and all Auth-owned personal data.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"recipient_email"
],
"properties": {
"recipient_email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true
},
"examples": [
{
"recipient_email": "former.user@example.com"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"external"
],
"externalAddress": "required"
},
"idempotency": {
"required": true,
"pattern": "^auth:account-deletion-completed:"
},
"sensitiveFields": [
"recipient_email"
]
},
{
"type": "platform.account.deletion_requested",
"version": 1,
"description": "Auth durably soft-deleted the account and scheduled its purge.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"scheduled_purge_at",
"recipient_email"
],
"properties": {
"scheduled_purge_at": {
"type": "string",
"format": "date-time"
},
"recipient_email": {
"type": "string",
"format": "email"
}
},
"additionalProperties": true
},
"examples": [
{
"scheduled_purge_at": "2026-08-19T00:00:00.000Z",
"recipient_email": "former.user@example.com"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"external"
],
"externalAddress": "required"
},
"idempotency": {
"required": true,
"pattern": "^auth:account-deletion-requested:"
},
"sensitiveFields": [
"recipient_email"
]
},
{
"type": "platform.welcome",
"version": 1,
"description": "Auth durably created a user account.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"display_name"
],
"properties": {
"display_name": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": true
},
"examples": [
{
"display_name": "Ada Lovelace"
}
],
"dataClassification": "confidential",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^auth:welcome:"
},
"sensitiveFields": []
}
]
},
"actions": [
{
"name": "organizations.list",
"title": "List organizations",
"description": "Read organizations visible to the authenticated Auth principal.",
"method": "GET",
"path": "/api/organizations",
"permission": "organizations:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List organizations.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"page": 1,
"limit": 1,
"includeDeleted": true
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.get",
"title": "Get organization",
"description": "Read organization details by organization id.",
"method": "GET",
"path": "/api/organizations/{orgId}",
"permission": "organizations:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get organization.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.export",
"title": "Export organization identity data",
"description": "Export the portable Auth-owned organization, membership, access, preference, session, and audit record set.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/export",
"permission": "organizations:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Export organization identity data.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/export",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/export",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.billable_seats.get",
"title": "Get organization billable seats",
"description": "Read the billable seat summary for one organization.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/billable-seat-summary",
"permission": "organizations:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get organization billable seats.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/billable-seat-summary",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/billable-seat-summary",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.create",
"title": "Create organization",
"description": "Create an organization and optionally invite its first owner.",
"target": "api",
"method": "POST",
"path": "/api/organizations",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create organization.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"name": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations",
"body": {
"name": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.update",
"title": "Update organization",
"description": "Update one organization.",
"target": "api",
"method": "PATCH",
"path": "/api/organizations/{orgId}",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update organization.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PATCH",
"path": "/api/organizations/example",
"body": {
"orgId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PATCH /api/organizations/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.delete",
"title": "Delete organization",
"description": "Soft-delete one organization and revoke its active sessions.",
"target": "api",
"method": "DELETE",
"path": "/api/organizations/{orgId}",
"permission": "organizations:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete organization.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/organizations/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/organizations/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.delete_permanently",
"title": "Permanently delete organization identity data",
"description": "Permanently purge Auth-owned data for one soft-deleted organization.",
"target": "api",
"method": "DELETE",
"path": "/api/organizations/{orgId}/permanent",
"permission": "organizations:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Permanently delete organization identity data.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/organizations/example/permanent",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/organizations/*/permanent",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.restore",
"title": "Restore organization",
"description": "Restore one soft-deleted organization.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/restore",
"permission": "organizations:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Restore organization.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/restore",
"body": {
"orgId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/restore",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organizations.owner_invite.resend",
"title": "Resend organization owner invite",
"description": "Issue a fresh owner invitation for one organization.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/resend-owner-invite",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Resend organization owner invite.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/resend-owner-invite",
"body": {
"orgId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/resend-owner-invite",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_principals.list",
"title": "List organization principals",
"description": "List human and headless principals assignable in one organization.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/principals",
"permission": "organizations:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List organization principals.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/principals",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/principals",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_principals.create",
"title": "Create organization principal",
"description": "Create a headless agent principal accountable to a human organization member.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/principals",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create organization principal.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"principalType": "agent_employee",
"displayName": "example",
"accountableUserId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/principals",
"body": {
"orgId": "example",
"principalType": "agent_employee",
"displayName": "example",
"accountableUserId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/principals",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_principals.update",
"title": "Update organization principal",
"description": "Update a headless organization principal and its service grants.",
"target": "api",
"method": "PATCH",
"path": "/api/organizations/{orgId}/principals/{principalId}",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update organization principal.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"principalId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PATCH",
"path": "/api/organizations/example/principals/example",
"body": {
"orgId": "example",
"principalId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PATCH /api/organizations/*/principals/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "principal_credentials.list",
"title": "List principal credentials",
"description": "List credentials issued to one headless principal.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/principals/{principalId}/credentials",
"permission": "api_keys:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List principal credentials.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example",
"principalId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/principals/example/credentials",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/principals/*/credentials",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "principal_credentials.issue",
"title": "Issue principal credential",
"description": "Issue a new client credential to one active headless principal.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/principals/{principalId}/credentials",
"permission": "api_keys:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Issue principal credential.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"principalId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/principals/example/credentials",
"body": {
"orgId": "example",
"principalId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/principals/*/credentials",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "principal_credentials.revoke",
"title": "Revoke principal credential",
"description": "Revoke one headless principal credential.",
"target": "api",
"method": "DELETE",
"path": "/api/organizations/{orgId}/principals/{principalId}/credentials/{credentialId}",
"permission": "api_keys:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke principal credential.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"principalId": "example",
"credentialId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/organizations/example/principals/example/credentials/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/organizations/*/principals/*/credentials/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_member_roles.assign",
"title": "Assign organization member role",
"description": "Assign an additional organization or application role to a member.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/members/{userId}/roles",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Assign organization member role.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"userId": "example",
"roleKey": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/members/example/roles",
"body": {
"orgId": "example",
"userId": "example",
"roleKey": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/members/*/roles",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_member_roles.revoke",
"title": "Revoke organization member role",
"description": "Revoke an additional organization or application role from a member.",
"target": "api",
"method": "DELETE",
"path": "/api/organizations/{orgId}/members/{userId}/roles/{roleKey}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke organization member role.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"userId": "example",
"roleKey": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/organizations/example/members/example/roles/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/organizations/*/members/*/roles/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_billing.preview",
"title": "Preview organization billing",
"description": "Preview billing for a proposed organization seat quantity.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/billing-preview",
"permission": "organizations:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Preview organization billing.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/billing-preview",
"body": {
"orgId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/billing-preview",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_billing.portal.create",
"title": "Create organization billing portal session",
"description": "Create a billing portal session for one organization.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/billing-portal",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create organization billing portal session.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/billing-portal",
"body": {
"orgId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/billing-portal",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_service_onboarding.complete",
"title": "Complete organization service onboarding",
"description": "Mark organization-wide onboarding complete for one installed service.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/services/{appId}/onboarding-complete",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Complete organization service onboarding.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/services/example/onboarding-complete",
"body": {
"orgId": "example",
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/services/*/onboarding-complete",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_service_onboarding.get",
"title": "Get my service onboarding progress",
"description": "Read the caller's onboarding progress for one installed service.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/services/{appId}/onboarding/me",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get my service onboarding progress.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/services/example/onboarding/me",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/services/*/onboarding/me",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_service_onboarding.update",
"title": "Update my service onboarding progress",
"description": "Replace the caller's onboarding progress for one installed service.",
"target": "api",
"method": "PUT",
"path": "/api/organizations/{orgId}/services/{appId}/onboarding/me",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update my service onboarding progress.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"progress": {
"currentStepId": "example",
"completedStepIds": [
"example"
],
"dismissedStepIds": [
"example"
]
}
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/organizations/example/services/example/onboarding/me",
"body": {
"orgId": "example",
"appId": "example",
"progress": {
"currentStepId": "example",
"completedStepIds": [
"example"
],
"dismissedStepIds": [
"example"
]
}
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/organizations/*/services/*/onboarding/me",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_service_tours.list",
"title": "List my service tour progress",
"description": "List the caller's tour progress for one installed service.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/services/{appId}/tours/me",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List my service tour progress.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/services/example/tours/me",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/services/*/tours/me",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_service_tours.update",
"title": "Update my service tour progress",
"description": "Replace the caller's progress for one service tour.",
"target": "api",
"method": "PUT",
"path": "/api/organizations/{orgId}/services/{appId}/tours/me",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update my service tour progress.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"tourId": "example",
"progress": {
"currentStep": 1,
"completed": true,
"skipped": true
}
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/organizations/example/services/example/tours/me",
"body": {
"orgId": "example",
"appId": "example",
"tourId": "example",
"progress": {
"currentStep": 1,
"completed": true,
"skipped": 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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/organizations/*/services/*/tours/me",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "households.list",
"title": "List my households",
"description": "List households available to the caller.",
"target": "api",
"method": "GET",
"path": "/api/households",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List my households.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/households",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/households",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "households.create",
"title": "Create household",
"description": "Create a household owned by the caller.",
"target": "api",
"method": "POST",
"path": "/api/households",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create household.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"name": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/households",
"body": {
"name": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/households",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "households.get",
"title": "Get household",
"description": "Read one household available to the caller.",
"target": "api",
"method": "GET",
"path": "/api/households/{householdId}",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"householdId": {
"type": "string",
"minLength": 1
}
},
"required": [
"householdId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get household.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"householdId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/households/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/households/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "households.update",
"title": "Update household",
"description": "Update one household managed by the caller.",
"target": "api",
"method": "PUT",
"path": "/api/households/{householdId}",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update household.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"householdId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/households/example",
"body": {
"householdId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/households/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "households.delete",
"title": "Delete household",
"description": "Delete one household managed by the caller.",
"target": "api",
"method": "DELETE",
"path": "/api/households/{householdId}",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"householdId": {
"type": "string",
"minLength": 1
}
},
"required": [
"householdId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete household.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"householdId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/households/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/households/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "household_members.add",
"title": "Add household member",
"description": "Add an existing or invited user to a household.",
"target": "api",
"method": "POST",
"path": "/api/households/{householdId}/members",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Add household member.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"householdId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/households/example/members",
"body": {
"householdId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/households/*/members",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "household_members.remove",
"title": "Remove household member",
"description": "Remove one user from a household.",
"target": "api",
"method": "DELETE",
"path": "/api/households/{householdId}/members",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Remove household member.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"householdId": "example",
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/households/example/members",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/households/*/members",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "household_dependents.add",
"title": "Add household dependent",
"description": "Attach an existing or new dependent to a household.",
"target": "api",
"method": "POST",
"path": "/api/households/{householdId}/dependents",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Add household dependent.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"householdId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/households/example/dependents",
"body": {
"householdId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/households/*/dependents",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "household_dependents.remove",
"title": "Remove household dependent",
"description": "Remove one dependent from a household.",
"target": "api",
"method": "DELETE",
"path": "/api/households/{householdId}/dependents",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Remove household dependent.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"householdId": "example",
"dependentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/households/example/dependents",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/households/*/dependents",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_service_relationships.list",
"title": "List organization service relationships",
"description": "List bounded organization-to-application access relationships across the platform.",
"target": "api",
"method": "GET",
"path": "/api/organization-services",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List organization service relationships.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"page": 1,
"limit": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organization-services",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organization-services",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_service_relationships.get",
"title": "Get organization service relationship",
"description": "Read one organization-to-application access relationship.",
"target": "api",
"method": "GET",
"path": "/api/organization-services/{relationshipId}",
"permission": "services:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"relationshipId": {
"type": "string",
"minLength": 1
}
},
"required": [
"relationshipId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get organization service relationship.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"relationshipId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organization-services/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organization-services/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_service_relationships.create",
"title": "Create organization service relationship",
"description": "Grant an organization access to one application.",
"target": "api",
"method": "POST",
"path": "/api/organization-services",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create organization service relationship.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"organizationId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organization-services",
"body": {
"organizationId": "example",
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organization-services",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_service_relationships.update",
"title": "Update organization service relationship",
"description": "Update one organization-to-application access relationship.",
"target": "api",
"method": "PUT",
"path": "/api/organization-services/{relationshipId}",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update organization service relationship.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"relationshipId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/organization-services/example",
"body": {
"relationshipId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/organization-services/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_service_relationships.delete",
"title": "Delete organization service relationship",
"description": "Revoke an organization application relationship.",
"target": "api",
"method": "DELETE",
"path": "/api/organization-services/{relationshipId}",
"permission": "organizations:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"relationshipId": {
"type": "string",
"minLength": 1
}
},
"required": [
"relationshipId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete organization service relationship.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"relationshipId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/organization-services/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/organization-services/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_service_relationships.check",
"title": "Check organization service access",
"description": "Check one exact organization and application relationship without enumerating the catalog.",
"target": "api",
"method": "GET",
"path": "/api/organization-services/check/{organizationId}/{appId}",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Check organization service access.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"organizationId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organization-services/check/example/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organization-services/check/*/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_organizations.list",
"title": "List service organizations",
"description": "List a bounded page of organizations with access to one application.",
"target": "api",
"method": "GET",
"path": "/api/services/{appId}/organizations",
"permission": "organizations:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List service organizations.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services/example/organizations",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services/*/organizations",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "invitations.list",
"title": "List invitations",
"description": "List a bounded page of organization invitations.",
"target": "api",
"method": "GET",
"path": "/api/invitations",
"permission": "organizations:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List invitations.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"organizationId": "example",
"page": 1,
"limit": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/invitations",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/invitations",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "invitations.create",
"title": "Create invitation",
"description": "Create an organization invitation and optionally notify its recipient.",
"target": "api",
"method": "POST",
"path": "/api/invitations",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create invitation.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"organizationId": "example",
"email": "user@example.com",
"role": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/invitations",
"body": {
"organizationId": "example",
"email": "user@example.com",
"role": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/invitations",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "invitations.delete",
"title": "Delete invitation",
"description": "Delete one organization invitation.",
"target": "api",
"method": "DELETE",
"path": "/api/invitations/{invitationId}",
"permission": "organizations:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"invitationId": {
"type": "string",
"minLength": 1
}
},
"required": [
"invitationId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete invitation.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"invitationId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/invitations/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/invitations/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "machine_registry.get",
"title": "Get machine launch metadata",
"description": "Resolve machine launch metadata for one exact accessible application.",
"target": "api",
"method": "GET",
"path": "/api/machine/registry",
"permission": "services:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"app_id": {
"type": "string",
"minLength": 1
}
},
"required": [
"app_id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get machine launch metadata.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"app_id": "00000000-0000-4000-8000-000000000000"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/machine/registry",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/machine/registry",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "machine_handoffs.create",
"title": "Create machine handoff",
"description": "Create a short-lived handoff for one exact accessible application and launch intent.",
"target": "api",
"method": "POST",
"path": "/api/machine/handoffs",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create machine handoff.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"app_id": "00000000-0000-4000-8000-000000000000",
"intent": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/machine/handoffs",
"body": {
"app_id": "00000000-0000-4000-8000-000000000000",
"intent": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/machine/handoffs",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_app_switcher_preferences.get",
"title": "Get my app switcher preferences",
"description": "Read the caller's bounded app switcher preferences.",
"target": "api",
"method": "GET",
"path": "/api/app-switcher/preferences",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"$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
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"agentContract": {
"effects": [
"Reads the authenticated caller only.",
"Returns the current monotonic preference revision."
],
"verification": [
"Compare data.revision with the last revision observed for this caller."
],
"examples": [
{}
]
},
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/app-switcher/preferences",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/app-switcher/preferences",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_app_switcher_preferences.events",
"title": "List my app switcher preference events",
"description": "List caller-owned preference revisions after an observed revision and return current state.",
"target": "api",
"method": "GET",
"path": "/api/app-switcher/preferences/events",
"permission": "users:read",
"inputSchema": {
"$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
},
"outputSchema": {
"$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
},
"agentContract": {
"effects": [
"Reads the authenticated caller only.",
"Does not consume or delete events."
],
"verification": [
"Continue from data.state.revision after applying the returned events."
],
"examples": [
{
"afterRevision": 0,
"limit": 50
}
]
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"afterRevision": 0,
"limit": 50
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/app-switcher/preferences/events",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/app-switcher/preferences/events",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_app_switcher_preferences.update",
"title": "Update my app switcher preferences",
"description": "Update the caller's bounded app switcher preferences.",
"target": "api",
"method": "PUT",
"path": "/api/app-switcher/preferences",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"$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
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"agentContract": {
"effects": [
"Merges only supplied preference fields.",
"Creates one caller-owned revision event."
],
"verification": [
"Success returns the committed revision and the same mutationId.",
"A 409 returns current state for merge and retry."
],
"recovery": [
"Retry an ambiguous request with the same mutationId.",
"On revision conflict, retain local dirty fields and retry against the returned revision."
],
"examples": [
{
"baseRevision": 0,
"mutationId": "cli-example-1",
"favorites": [
"app_topolo_one"
]
}
]
},
"documentation": {
"example_input": {
"baseRevision": 0,
"mutationId": "cli-example-1",
"favorites": [
"app_topolo_one"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/app-switcher/preferences",
"body": {
"baseRevision": 0,
"mutationId": "cli-example-1",
"favorites": [
"app_topolo_one"
]
}
},
"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."
]
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/app-switcher/preferences",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_i18n_preferences.get",
"title": "Get my language preferences",
"description": "Resolve the caller's language preferences.",
"target": "api",
"method": "GET",
"path": "/api/i18n/preferences",
"permission": "users:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get my language preferences.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"org_id": "00000000-0000-4000-8000-000000000000",
"locale": "en-US",
"lang": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/i18n/preferences",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/i18n/preferences",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "my_i18n_preferences.update",
"title": "Update my language preferences",
"description": "Update the caller's language preference.",
"target": "api",
"method": "PUT",
"path": "/api/i18n/preferences",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"locale": {
"type": "string",
"minLength": 1
},
"language": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update my language preferences.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"locale": "en-US",
"language": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/i18n/preferences",
"body": {
"locale": "en-US",
"language": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/i18n/preferences",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_preferences.list",
"title": "List user notification preferences",
"description": "List notification preferences for the caller or a platform-managed user.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/notification-preferences",
"permission": "users:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List user notification preferences.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/notification-preferences",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/notification-preferences",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_preferences.replace",
"title": "Replace user notification preferences",
"description": "Replace the bounded notification preference set for the caller or a platform-managed user.",
"target": "api",
"method": "PUT",
"path": "/api/users/{userId}/notification-preferences",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Replace user notification preferences.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"rows": [
{
"event_type": "system.example",
"channel": "email",
"enabled": true
}
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/users/example/notification-preferences",
"body": {
"userId": "example",
"rows": [
{
"event_type": "system.example",
"channel": "email",
"enabled": 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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/users/*/notification-preferences",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_preferences.resolve",
"title": "Resolve user notification preferences",
"description": "Resolve effective delivery channels and action policy for one user and event.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/notification-preferences/resolve",
"permission": "users:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Resolve user notification preferences.",
"additionalProperties": true
},
"agentContract": {
"examples": [
{
"userId": "user_demo",
"org_id": "org_topolo_platform",
"event_type": "campaigns.send_completed"
}
]
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "user_demo",
"org_id": "org_topolo_platform",
"event_type": "campaigns.send_completed"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/user_demo/notification-preferences/resolve",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/notification-preferences/resolve",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_channels.list",
"title": "List user notification channels",
"description": "List verified and pending notification addresses for one visible user.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/notification-channels",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List user notification channels.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/notification-channels",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/notification-channels",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_channels.create",
"title": "Create user notification channel",
"description": "Register a notification address for one visible user.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/notification-channels",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create user notification channel.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"channel": "email",
"address": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/notification-channels",
"body": {
"userId": "example",
"channel": "email",
"address": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/notification-channels",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_channels.verify",
"title": "Verify user notification channel",
"description": "Mark one notification address as verified.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/notification-channels/{channelId}/verify",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Verify user notification channel.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"channelId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/notification-channels/example/verify",
"body": {
"userId": "example",
"channelId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/notification-channels/*/verify",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_channels.delete",
"title": "Delete user notification channel",
"description": "Delete one notification address from a visible user.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}/notification-channels/{channelId}",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete user notification channel.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"channelId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example/notification-channels/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*/notification-channels/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_notification_policy.list",
"title": "List organization notification policy",
"description": "List delivery rules enforced by one managed organization.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/notification-policy",
"permission": "organizations:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List organization notification policy.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/notification-policy",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/notification-policy",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_notification_policy.replace",
"title": "Replace organization notification policy",
"description": "Replace delivery rules enforced by one managed organization.",
"target": "api",
"method": "PUT",
"path": "/api/organizations/{orgId}/notification-policy",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Replace organization notification policy.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"rows": [
{
"event_type": "system.example",
"channel": "email",
"forbidden": true
}
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/organizations/example/notification-policy",
"body": {
"orgId": "example",
"rows": [
{
"event_type": "system.example",
"channel": "email",
"forbidden": 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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/organizations/*/notification-policy",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_notification_action_policy.list",
"title": "List organization notification action policy",
"description": "List action-delivery policy rules for one managed organization.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/notification-action-policy",
"permission": "organizations:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List organization notification action policy.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/notification-action-policy",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/notification-action-policy",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_notification_action_policy.replace",
"title": "Replace organization notification action policy",
"description": "Replace action-delivery policy rules for one managed organization.",
"target": "api",
"method": "PUT",
"path": "/api/organizations/{orgId}/notification-action-policy",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Replace organization notification action policy.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"rows": [
{
"delivery_mode": "immediate",
"required_action": true,
"enabled": true
}
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/organizations/example/notification-action-policy",
"body": {
"orgId": "example",
"rows": [
{
"delivery_mode": "immediate",
"required_action": true,
"enabled": 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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/organizations/*/notification-action-policy",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_action_policy.list",
"title": "List user notification action policy",
"description": "List action-delivery policy rules for the caller or a user in a managed organization.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/users/{userId}/notification-action-policy",
"permission": "users:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List user notification action policy.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example",
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/users/example/notification-action-policy",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/users/*/notification-action-policy",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_notification_action_policy.replace",
"title": "Replace user notification action policy",
"description": "Replace action-delivery policy rules for the caller or a user in a managed organization.",
"target": "api",
"method": "PUT",
"path": "/api/organizations/{orgId}/users/{userId}/notification-action-policy",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Replace user notification action policy.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"userId": "example",
"rows": [
{
"delivery_mode": "immediate",
"required_action": true,
"enabled": true
}
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/organizations/example/users/example/notification-action-policy",
"body": {
"orgId": "example",
"userId": "example",
"rows": [
{
"delivery_mode": "immediate",
"required_action": true,
"enabled": 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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/organizations/*/users/*/notification-action-policy",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "developer_oauth_connected_apps.list",
"title": "List my connected OAuth apps",
"description": "List developer OAuth applications currently connected to the caller.",
"target": "api",
"method": "GET",
"path": "/api/developer-oauth/connected-apps",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List my connected OAuth apps.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/developer-oauth/connected-apps",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/developer-oauth/connected-apps",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "developer_oauth_connected_apps.disconnect",
"title": "Disconnect OAuth app",
"description": "Revoke the caller's refresh tokens for one connected OAuth client.",
"target": "api",
"method": "DELETE",
"path": "/api/developer-oauth/connected-apps/{clientId}",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"clientId": {
"type": "string",
"minLength": 1
}
},
"required": [
"clientId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Disconnect OAuth app.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"clientId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/developer-oauth/connected-apps/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/developer-oauth/connected-apps/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "developer_oauth_clients.list",
"title": "List developer OAuth clients",
"description": "List OAuth clients owned by the caller's developer organization.",
"target": "api",
"method": "GET",
"path": "/api/developer-oauth/clients",
"permission": "services:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List developer OAuth clients.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/developer-oauth/clients",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/developer-oauth/clients",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "developer_oauth_clients.create",
"title": "Create developer OAuth client",
"description": "Create an OAuth client for the caller's developer organization and return its secret once when confidential.",
"target": "api",
"method": "POST",
"path": "/api/developer-oauth/clients",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create developer OAuth client.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"name": "example",
"developer_id": "00000000-0000-4000-8000-000000000000"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/developer-oauth/clients",
"body": {
"name": "example",
"developer_id": "00000000-0000-4000-8000-000000000000"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/developer-oauth/clients",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "developer_oauth_clients.rotate_secret",
"title": "Rotate developer OAuth client secret",
"description": "Rotate and return the secret for one confidential OAuth client.",
"target": "api",
"method": "POST",
"path": "/api/developer-oauth/clients/{id}/rotate-secret",
"permission": "services:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
}
},
"required": [
"id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Rotate developer OAuth client secret.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"id": "00000000-0000-4000-8000-000000000000"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/developer-oauth/clients/00000000-0000-4000-8000-000000000000/rotate-secret",
"body": {
"id": "00000000-0000-4000-8000-000000000000"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/developer-oauth/clients/*/rotate-secret",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "developer_oauth_clients.revoke",
"title": "Revoke developer OAuth client",
"description": "Revoke one OAuth client and all of its active refresh tokens.",
"target": "api",
"method": "DELETE",
"path": "/api/developer-oauth/clients/{id}",
"permission": "services:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
}
},
"required": [
"id"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke developer OAuth client.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"id": "00000000-0000-4000-8000-000000000000"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/developer-oauth/clients/00000000-0000-4000-8000-000000000000",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/developer-oauth/clients/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_config.get",
"title": "Get application login config",
"description": "Read merged login branding and active event config for one application.",
"target": "api",
"method": "GET",
"path": "/api/login-config/{appId}",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get application login config.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"authorizationMode": "public",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/login-config/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/login-config/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_config.update",
"title": "Update application login config",
"description": "Update only the supplied login config fields for one application.",
"target": "api",
"method": "PUT",
"path": "/api/login-config/{appId}",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update application login config.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/login-config/example",
"body": {
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/login-config/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "master_login_config.get",
"title": "Get master login config",
"description": "Read the platform-wide default login branding config.",
"target": "api",
"method": "GET",
"path": "/api/login-config-master",
"permission": "services:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get master login config.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/login-config-master",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/login-config-master",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "master_login_config.update",
"title": "Update master login config",
"description": "Update only the supplied platform-wide default login fields.",
"target": "api",
"method": "PUT",
"path": "/api/login-config-master",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update master login config.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"brand_name": "example",
"brand_tagline": "example",
"brand_logo_url": "https://example.com"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/login-config-master",
"body": {
"brand_name": "example",
"brand_tagline": "example",
"brand_logo_url": "https://example.com"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/login-config-master",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "landing_config.get",
"title": "Get application landing config",
"description": "Read the app-specific landing presentation, returning-user login action, and policy-controlled signup journey for one application.",
"target": "api",
"method": "GET",
"path": "/api/landing-config/{appId}",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get application landing config.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"authorizationMode": "public",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/landing-config/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/landing-config/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "landing_config.update",
"title": "Update application landing config",
"description": "Create or update supplied landing-page fields for one application.",
"target": "api",
"method": "PUT",
"path": "/api/landing-config/{appId}",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update application landing config.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/landing-config/example",
"body": {
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/landing-config/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "app_ui_config.get",
"title": "Get application UI config",
"description": "Read shared authenticated-shell colors and notes for one application.",
"target": "api",
"method": "GET",
"path": "/api/app-ui-config/{appId}",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get application UI config.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"authorizationMode": "public",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/app-ui-config/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/app-ui-config/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "app_ui_config.update",
"title": "Update application UI config",
"description": "Update only supplied authenticated-shell fields for one application.",
"target": "api",
"method": "PUT",
"path": "/api/app-ui-config/{appId}",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update application UI config.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/app-ui-config/example",
"body": {
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/app-ui-config/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_events.list",
"title": "List login events",
"description": "List a bounded page of scheduled login themes.",
"target": "api",
"method": "GET",
"path": "/api/login-events",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List login events.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"limit": 1,
"cursor": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/login-events",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/login-events",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_events.create",
"title": "Create login event",
"description": "Create a scheduled login theme for selected applications or the platform.",
"target": "api",
"method": "POST",
"path": "/api/login-events",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create login event.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"name": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/login-events",
"body": {
"name": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/login-events",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_events.update",
"title": "Update login event",
"description": "Update supplied fields on one scheduled login theme.",
"target": "api",
"method": "PUT",
"path": "/api/login-events/{eventId}",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update login event.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"eventId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/login-events/example",
"body": {
"eventId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/login-events/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_events.delete",
"title": "Delete login event",
"description": "Delete one scheduled login theme.",
"target": "api",
"method": "DELETE",
"path": "/api/login-events/{eventId}",
"permission": "services:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"eventId": {
"type": "string",
"minLength": 1
}
},
"required": [
"eventId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete login event.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"eventId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/login-events/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/login-events/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_presets.list",
"title": "List login presets",
"description": "List a bounded page of reusable login theme presets.",
"target": "api",
"method": "GET",
"path": "/api/login-presets",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List login presets.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"limit": 1,
"cursor": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/login-presets",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/login-presets",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_presets.create",
"title": "Create login preset",
"description": "Create a reusable login theme preset.",
"target": "api",
"method": "POST",
"path": "/api/login-presets",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create login preset.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"name": "example",
"config": {}
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/login-presets",
"body": {
"name": "example",
"config": {}
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/login-presets",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "login_presets.delete",
"title": "Delete login preset",
"description": "Delete one non-system login theme preset.",
"target": "api",
"method": "DELETE",
"path": "/api/login-presets/{presetId}",
"permission": "services:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"presetId": {
"type": "string",
"minLength": 1
}
},
"required": [
"presetId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete login preset.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"presetId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/login-presets/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/login-presets/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "platform_pricing.get",
"title": "Get platform pricing",
"description": "Read the platform-wide pricing configuration.",
"target": "api",
"method": "GET",
"path": "/api/admin/platform-pricing",
"permission": "services:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get platform pricing.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/platform-pricing",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/admin/platform-pricing",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "platform_pricing.update",
"title": "Update platform pricing",
"description": "Update the platform-wide pricing configuration.",
"target": "api",
"method": "PUT",
"path": "/api/admin/platform-pricing",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update platform pricing.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"base": {
"planId": "example",
"monthlyCentsPerSeat": 1
},
"includedFreeInBase": [
{
"appId": "example",
"headline": "example"
}
],
"platformCapabilities": [
"example"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/admin/platform-pricing",
"body": {
"base": {
"planId": "example",
"monthlyCentsPerSeat": 1
},
"includedFreeInBase": [
{
"appId": "example",
"headline": "example"
}
],
"platformCapabilities": [
"example"
]
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/admin/platform-pricing",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "app_pricing_plans.list",
"title": "List application pricing plans",
"description": "List pricing plans registered for one application.",
"target": "api",
"method": "GET",
"path": "/api/admin/pricing-plans/by-app/{appId}",
"permission": "services:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List application pricing plans.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/pricing-plans/by-app/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/admin/pricing-plans/by-app/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "app_pricing_plans.bulk_register",
"title": "Bulk register application pricing plans",
"description": "Create or update a bounded set of application pricing plans.",
"target": "api",
"method": "POST",
"path": "/api/admin/pricing-plans/bulk-register",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Bulk register application pricing plans.",
"additionalProperties": true
},
"agentContract": {
"examples": [
{
"plans": [
{
"id": "demo_monthly",
"displayName": "Demo Monthly",
"pricingModel": "flat"
}
]
}
]
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"plans": [
{
"id": "demo_monthly",
"displayName": "Demo Monthly",
"pricingModel": "flat"
}
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/pricing-plans/bulk-register",
"body": {
"plans": [
{
"id": "demo_monthly",
"displayName": "Demo Monthly",
"pricingModel": "flat"
}
]
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/admin/pricing-plans/bulk-register",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "app_pricing_meters.register",
"title": "Register application pricing meters",
"description": "Create or update application usage meters and plan quotas.",
"target": "api",
"method": "POST",
"path": "/api/admin/billing/register-app-pricing",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Register application pricing meters.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example",
"meters": [
{
"key": "example",
"displayName": "example",
"unit": "example"
}
],
"quotas": [
{
"pricingPlanId": "example",
"meterKey": "example",
"includedPerSeat": 1,
"includedFlat": 1
}
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/billing/register-app-pricing",
"body": {
"appId": "example",
"meters": [
{
"key": "example",
"displayName": "example",
"unit": "example"
}
],
"quotas": [
{
"pricingPlanId": "example",
"meterKey": "example",
"includedPerSeat": 1,
"includedFlat": 1
}
]
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/admin/billing/register-app-pricing",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "resource_grants.list_mine",
"title": "List my resource grants",
"description": "List a bounded page of the caller's live resource grants.",
"target": "api",
"method": "GET",
"path": "/api/resource-grants/me",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List my resource grants.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"org_id": "00000000-0000-4000-8000-000000000000",
"app_id": "00000000-0000-4000-8000-000000000000",
"limit": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/resource-grants/me",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/resource-grants/me",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "resource_grants.create",
"title": "Create resource grant",
"description": "Grant a user access to one application resource when the caller can manage the organization or target application grants.",
"target": "api",
"method": "POST",
"path": "/api/resource-grants",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create resource grant.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"organizationId": "example",
"appId": "example",
"resourceType": "example",
"resourceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/resource-grants",
"body": {
"organizationId": "example",
"appId": "example",
"resourceType": "example",
"resourceId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/resource-grants",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "resource_grants.revoke",
"title": "Revoke resource grant",
"description": "Revoke one resource grant when the caller can manage its organization.",
"target": "api",
"method": "POST",
"path": "/api/resource-grants/{grantId}/revoke",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke resource grant.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"grantId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/resource-grants/example/revoke",
"body": {
"grantId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/resource-grants/*/revoke",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "resource_grants.promote",
"title": "Promote resource-grant user",
"description": "Promote a scoped user to an organization member when the caller can manage the organization or target application grants.",
"target": "api",
"method": "POST",
"path": "/api/resource-grants/promote",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Promote resource-grant user.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"organizationId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/resource-grants/promote",
"body": {
"userId": "example",
"organizationId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/resource-grants/promote",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspaces.list",
"title": "List workspaces",
"description": "List active canonical workspaces the caller may use in one application and organization.",
"target": "api",
"method": "GET",
"path": "/api/workspaces",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List workspaces.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "data.workspaces[].id"
},
"effects": [
"Reads canonical workspace identity, ownership, access, and default state from Topolo Auth."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the closed input schema and retry."
},
{
"status": 401,
"code": "UNAUTHORIZED",
"recovery": "Authenticate as the user acting in this workspace."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use an application and organization the caller may access; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh canonical workspace discovery and confirm the workspace is still active."
}
],
"verify": [
"Use only workspace ids returned for the requested app_id and org_id.",
"Confirm exactly one active workspace is marked as the application default."
],
"nextActionIds": [
"app_topolo_auth.workspaces.create",
"app_topolo_auth.workspaces.rename",
"app_topolo_auth.workspaces.default.set"
],
"examples": [
{
"org_id": "org_acme",
"app_id": "app_topolo_campaigns"
}
],
"recovery": "Refresh the active organization and application context before retrying discovery."
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"org_id": "org_acme",
"app_id": "app_topolo_campaigns"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/workspaces",
"body": null
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "data.workspaces[].id"
},
"next_action_ids": [
"app_topolo_auth.workspaces.create",
"app_topolo_auth.workspaces.rename",
"app_topolo_auth.workspaces.default.set"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/workspaces",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspaces.create",
"title": "Create workspace",
"description": "Create one canonical workspace for an application and organization.",
"target": "api",
"method": "POST",
"path": "/api/workspaces",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create workspace.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "data.workspace.id"
},
"effects": [
"Creates canonical workspace identity in Topolo Auth.",
"Makes the first active workspace the default, or honors isDefault when explicitly requested."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the closed input schema and retry."
},
{
"status": 401,
"code": "UNAUTHORIZED",
"recovery": "Authenticate as the user acting in this workspace."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use an application and organization the caller may access; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh canonical workspace discovery and confirm the workspace is still active."
}
],
"verify": [
"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."
],
"nextActionIds": [
"app_topolo_auth.workspaces.list"
],
"examples": [
{
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"name": "Launch operations"
}
],
"recovery": "Refresh workspace discovery before retrying so a successful response is not duplicated after a network timeout."
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"name": "Launch operations"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/workspaces",
"body": {
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"name": "Launch operations"
}
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "data.workspace.id"
},
"next_action_ids": [
"app_topolo_auth.workspaces.list"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/workspaces",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspaces.rename",
"title": "Rename workspace",
"description": "Rename canonical workspace presentation without changing its stable id or slug.",
"target": "api",
"method": "PATCH",
"path": "/api/workspaces/{workspaceId}",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Rename workspace.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "workspaceId"
},
"effects": [
"Changes only the canonical display name.",
"Preserves the workspace id, slug, ownership, membership, and application data."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the closed input schema and retry."
},
{
"status": 401,
"code": "UNAUTHORIZED",
"recovery": "Authenticate as the user acting in this workspace."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use an application and organization the caller may access; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh canonical workspace discovery and confirm the workspace is still active."
}
],
"verify": [
"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."
],
"nextActionIds": [
"app_topolo_auth.workspaces.list"
],
"examples": [
{
"workspaceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"name": "Customer launch"
}
],
"recovery": "Rediscover the workspace before retrying if ownership or organization context changed."
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"workspaceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"name": "Customer launch"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PATCH",
"path": "/api/workspaces/workspace_123",
"body": {
"workspaceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"name": "Customer launch"
}
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "workspaceId"
},
"next_action_ids": [
"app_topolo_auth.workspaces.list"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PATCH /api/workspaces/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspaces.default.set",
"title": "Set default workspace",
"description": "Set the single canonical default workspace for an application and organization.",
"target": "api",
"method": "PUT",
"path": "/api/workspaces/{workspaceId}/default",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Set default workspace.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "workspaceId"
},
"effects": [
"Atomically makes this the only active default workspace for the application and organization."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the closed input schema and retry."
},
{
"status": 401,
"code": "UNAUTHORIZED",
"recovery": "Authenticate as the user acting in this workspace."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use an application and organization the caller may access; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh canonical workspace discovery and confirm the workspace is still active."
},
{
"status": 409,
"code": "CONFLICT",
"recovery": "Refresh canonical workspace state and retry only if this workspace should still become the default."
}
],
"verify": [
"Run workspaces.list and confirm exactly this workspace is marked as default."
],
"nextActionIds": [
"app_topolo_auth.workspaces.list"
],
"examples": [
{
"workspaceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns"
}
],
"recovery": "Do not infer default state after a conflict; rediscover it from Topolo Auth."
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"workspaceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/workspaces/workspace_123/default",
"body": {
"workspaceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns"
}
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspaces/",
"resource": {
"kind": "workspace",
"idPath": "workspaceId"
},
"next_action_ids": [
"app_topolo_auth.workspaces.list"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/workspaces/*/default",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace_access.list_mine",
"title": "List accessible workspaces",
"description": "List active workspaces the caller may access in one application and organization.",
"target": "api",
"method": "GET",
"path": "/api/workspace-access/me",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List accessible workspaces.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_access",
"idPath": "data.resources[].resourceId"
},
"effects": [
"Reads the caller-specific workspace projection without changing access."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the field identified by the closed input schema and retry."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use the workspace owner or an organization owner or super admin; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh workspace discovery and confirm the workspace still exists in this application and organization."
}
],
"verify": [
"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."
],
"nextActionIds": [
"app_topolo_auth.workspace_access.members.list"
],
"examples": [
{
"org_id": "org_acme",
"app_id": "app_topolo_campaigns"
}
],
"recovery": "Refresh the active organization context and repeat discovery before retrying a denied workspace action."
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"org_id": "org_acme",
"app_id": "app_topolo_campaigns"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/workspace-access/me",
"body": null
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_access",
"idPath": "data.resources[].resourceId"
},
"next_action_ids": [
"app_topolo_auth.workspace_access.members.list"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/workspace-access/me",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace_access.members.list",
"title": "List workspace members",
"description": "List the owner, explicit members, and eligible same-organization assignees for one workspace.",
"target": "api",
"method": "GET",
"path": "/api/workspace-access/{resourceId}/members",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List workspace members.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace",
"idPath": "resourceId"
},
"effects": [
"Reads workspace ownership, member grants, and assignable same-organization users."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the field identified by the closed input schema and retry."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use the workspace owner or an organization owner or super admin; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh workspace discovery and confirm the workspace still exists in this application and organization."
}
],
"verify": [
"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."
],
"nextActionIds": [
"app_topolo_auth.workspace_access.members.grant",
"app_topolo_auth.workspace_ownership.transfer"
],
"examples": [
{
"resourceId": "workspace_123",
"org_id": "org_acme",
"app_id": "app_topolo_campaigns"
}
],
"recovery": "Run workspace_access.list_mine and retry with a currently accessible workspace."
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"resourceId": "workspace_123",
"org_id": "org_acme",
"app_id": "app_topolo_campaigns"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/workspace-access/workspace_123/members",
"body": null
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace",
"idPath": "resourceId"
},
"next_action_ids": [
"app_topolo_auth.workspace_access.members.grant",
"app_topolo_auth.workspace_ownership.transfer"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/workspace-access/*/members",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace_access.members.grant",
"title": "Grant workspace access",
"description": "Grant an active same-organization app member access to one workspace.",
"target": "api",
"method": "POST",
"path": "/api/workspace-access/{resourceId}/members",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Grant workspace access.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_member_grant",
"idPath": "data.grant.id"
},
"effects": [
"Creates or reactivates one workspace member grant.",
"Does not create organization membership, app entitlement, a seat, or ownership."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the field identified by the closed input schema and retry."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use the workspace owner or an organization owner or super admin; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh workspace discovery and confirm the workspace still exists in this application and organization."
}
],
"verify": [
"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."
],
"rollbackActionId": "app_topolo_auth.workspace_access.members.revoke",
"nextActionIds": [
"app_topolo_auth.workspace_access.members.list"
],
"examples": [
{
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"userId": "usr_member",
"scope": "read_write"
}
],
"recovery": "Confirm the target already belongs to the organization and has app access, then retry without provisioning a new identity."
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"userId": "usr_member",
"scope": "read_write"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/workspace-access/workspace_123/members",
"body": {
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"userId": "usr_member",
"scope": "read_write"
}
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_member_grant",
"idPath": "data.grant.id"
},
"next_action_ids": [
"app_topolo_auth.workspace_access.members.list"
],
"rollback_action_id": "app_topolo_auth.workspace_access.members.revoke"
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/workspace-access/*/members",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace_access.members.revoke",
"title": "Revoke workspace access",
"description": "Revoke one explicit workspace member grant without changing organization membership.",
"target": "api",
"method": "POST",
"path": "/api/workspace-access/{resourceId}/members/revoke",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke workspace access.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_member_grant",
"idPath": "data.userId"
},
"effects": [
"Revokes the target user explicit access to this workspace.",
"Does not remove organization membership, app entitlement, a seat, or access to other workspaces."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the field identified by the closed input schema and retry."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use the workspace owner or an organization owner or super admin; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh workspace discovery and confirm the workspace still exists in this application and organization."
}
],
"verify": [
"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."
],
"nextActionIds": [
"app_topolo_auth.workspace_access.members.list"
],
"examples": [
{
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"userId": "usr_member",
"reason": "Campaign complete"
}
],
"recovery": "If the user is the current owner, transfer ownership first; owner access cannot be revoked as a member grant."
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"userId": "usr_member",
"reason": "Campaign complete"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/workspace-access/workspace_123/members/revoke",
"body": {
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"userId": "usr_member",
"reason": "Campaign complete"
}
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_member_grant",
"idPath": "data.userId"
},
"next_action_ids": [
"app_topolo_auth.workspace_access.members.list"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/workspace-access/*/members/revoke",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace_ownership.transfer",
"title": "Transfer workspace ownership",
"description": "Atomically transfer the single primary owner role to an active same-organization app member.",
"target": "api",
"method": "POST",
"path": "/api/workspace-access/{resourceId}/transfer",
"authorizationMode": "runtime",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Transfer workspace ownership.",
"additionalProperties": true
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_ownership",
"idPath": "data.ownership.resourceId"
},
"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."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the field identified by the closed input schema and retry."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use the workspace owner or an organization owner or super admin; do not widen the caller role."
},
{
"status": 404,
"code": "NOT_FOUND",
"recovery": "Refresh workspace discovery and confirm the workspace still exists in this application and organization."
},
{
"status": 409,
"code": "CONFLICT",
"recovery": "Refresh workspace members because ownership changed, then retry only if the transfer is still intended."
}
],
"verify": [
"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."
],
"nextActionIds": [
"app_topolo_auth.workspace_access.members.list"
],
"examples": [
{
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"newOwnerUserId": "usr_new_owner",
"retainPreviousOwnerAccess": true
}
],
"recovery": "Do not retry blindly after a conflict; rediscover the current owner and require a fresh transfer decision."
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"newOwnerUserId": "usr_new_owner",
"retainPreviousOwnerAccess": true
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/workspace-access/workspace_123/transfer",
"body": {
"resourceId": "workspace_123",
"organizationId": "org_acme",
"appId": "app_topolo_campaigns",
"newOwnerUserId": "usr_new_owner",
"retainPreviousOwnerAccess": 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."
],
"docs_url": "https://docs.topolo.app/platform/workspace-access/",
"resource": {
"kind": "workspace_ownership",
"idPath": "data.ownership.resourceId"
},
"next_action_ids": [
"app_topolo_auth.workspace_access.members.list"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/workspace-access/*/transfer",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "me.get",
"title": "Get my Auth profile",
"description": "Read the caller's current Auth identity, context, and optional service permissions.",
"target": "api",
"method": "GET",
"path": "/api/me",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get my Auth profile.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"authorizationMode": "runtime",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/me",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/me",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "me.tenant.get",
"title": "Get my organization",
"description": "Read the organization selected by the caller's credential-bound context.",
"target": "api",
"method": "GET",
"path": "/api/tenant",
"permission": "organizations:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get my organization.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/tenant",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/tenant",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "me.recovery_email.get",
"title": "Get my recovery email",
"description": "Read the caller's personal recovery email status.",
"target": "api",
"method": "GET",
"path": "/api/me/recovery-email",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get my recovery email.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/me/recovery-email",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/me/recovery-email",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "me.recovery_email.request_verification",
"title": "Request recovery email verification",
"description": "Set the caller's personal recovery email and send a verification request.",
"target": "api",
"method": "POST",
"path": "/api/me/recovery-email",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Request recovery email verification.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"email": "user@example.com"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/me/recovery-email",
"body": {
"email": "user@example.com"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/me/recovery-email",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "me.sessions.revoke_all",
"title": "Revoke all my sessions",
"description": "Revoke every access token, refresh token, and session belonging to the caller.",
"target": "api",
"method": "POST",
"path": "/api/auth/logout-everywhere",
"permission": "sessions:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke all my sessions.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/auth/logout-everywhere",
"body": {}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/auth/logout-everywhere",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.list",
"title": "List users",
"description": "Read users visible to the authenticated Auth principal.",
"method": "GET",
"path": "/api/users",
"permission": "users:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List users.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"page": 1,
"limit": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.get",
"title": "Get user",
"description": "Read one user and their visible security state.",
"method": "GET",
"path": "/api/users/{userId}",
"permission": "users:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get user.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.export",
"title": "Export user identity data",
"description": "Export the portable Auth-owned identity, access, preference, session, and audit record set for one user.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/export",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Export user identity data.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/export",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/export",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_users.list",
"title": "List organization users",
"description": "List users in one organization, including deleted organizations when explicitly requested.",
"target": "api",
"method": "GET",
"path": "/api/users/organization/{orgId}",
"permission": "users:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List organization users.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/organization/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/organization/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.create",
"title": "Create user",
"description": "Create a user in an organization managed by the caller.",
"target": "api",
"method": "POST",
"path": "/api/users",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create user.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"email": "user@example.com",
"name": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users",
"body": {
"email": "user@example.com",
"name": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.update",
"title": "Update user",
"description": "Update one user profile or organization role.",
"target": "api",
"method": "PUT",
"path": "/api/users/{userId}",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update user.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/users/example",
"body": {
"userId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/users/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.status.update",
"title": "Update user status",
"description": "Activate or suspend one user.",
"target": "api",
"method": "PATCH",
"path": "/api/users/{userId}/status",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update user status.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"isActive": true
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PATCH",
"path": "/api/users/example/status",
"body": {
"userId": "example",
"isActive": 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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PATCH /api/users/*/status",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.delete",
"title": "Delete user",
"description": "Soft-delete one user, revoke their sessions, and release their email address.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}",
"permission": "users:delete",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete user.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.delete_permanently",
"title": "Permanently delete user",
"description": "Permanently purge Auth-owned data for one deleted user.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}/permanent",
"permission": "users:delete",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Permanently delete user.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example/permanent",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*/permanent",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_permissions.get",
"title": "Get user permissions",
"description": "Evaluate one user's effective permissions, optionally for one service.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/permissions",
"permission": "permissions:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get user permissions.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/permissions",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/permissions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_permission_overrides.list",
"title": "List user permission overrides",
"description": "List explicit allow and deny overrides for one user.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/service-permissions",
"permission": "permissions:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List user permission overrides.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/service-permissions",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/service-permissions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_permission_overrides.create",
"title": "Create user permission override",
"description": "Create an explicit service permission allow or deny override for one user.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/service-permissions",
"permission": "permissions:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create user permission override.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"orgId": "example",
"appId": "example",
"permissionName": "example",
"effect": "allow"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/service-permissions",
"body": {
"userId": "example",
"orgId": "example",
"appId": "example",
"permissionName": "example",
"effect": "allow"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/service-permissions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_permission_overrides.delete",
"title": "Delete user permission override",
"description": "Delete one explicit user permission override.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}/service-permissions/{overrideId}",
"permission": "permissions:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete user permission override.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"overrideId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example/service-permissions/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*/service-permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_service_access.get",
"title": "Get user service access",
"description": "Read one user's effective application access and seat assignments.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/service-access",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get user service access.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/service-access",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/service-access",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_service_access.replace",
"title": "Replace user service access",
"description": "Replace one user's assigned applications across organization-enabled services.",
"target": "api",
"method": "PUT",
"path": "/api/users/{userId}/service-access",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Replace user service access.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"appIds": [
"example"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/users/example/service-access",
"body": {
"userId": "example",
"appIds": [
"example"
]
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/users/*/service-access",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sessions.list",
"title": "List user sessions",
"description": "Read sessions for the caller or a managed user.",
"method": "GET",
"path": "/api/users/{userId}/sessions",
"permission": "sessions:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List user sessions.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/sessions",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/sessions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sessions.delete",
"title": "Delete user session",
"description": "Revoke one session belonging to the caller or a managed user.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}/sessions/{sessionId}",
"permission": "sessions:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete user session.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"sessionId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example/sessions/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*/sessions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_oauth_providers.list",
"title": "List user OAuth providers",
"description": "List external sign-in providers linked to one visible user.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/oauth-providers",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List user OAuth providers.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/oauth-providers",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/oauth-providers",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_oauth_providers.unlink",
"title": "Unlink user OAuth provider",
"description": "Unlink one external sign-in provider from a visible user.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}/oauth-providers/{provider}",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Unlink user OAuth provider.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"provider": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example/oauth-providers/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*/oauth-providers/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "users.unlock",
"title": "Unlock user account",
"description": "Clear the failed-login lockout for one managed user.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/unlock",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Unlock user account.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/unlock",
"body": {
"userId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/unlock",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "admin.mfa_protection.canary",
"title": "Check Auth MFA protection",
"description": "Verify that every retained MFA secret is protected and every backup code is hash-only.",
"target": "api",
"method": "GET",
"path": "/api/admin/privacy/mfa-protection/canary",
"permission": "audit:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Check Auth MFA protection.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/privacy/mfa-protection/canary",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/admin/privacy/mfa-protection/canary",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_security.get",
"title": "Get user security status",
"description": "Read MFA, passkey, backup-code, and account-lock status for one visible user.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/2fa-status",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get user security status.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/2fa-status",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/2fa-status",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_mfa.setup",
"title": "Begin user MFA setup",
"description": "Create a time-limited MFA setup secret, QR code, backup codes, and verification token.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/mfa/setup",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Begin user MFA setup.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/mfa/setup",
"body": {
"userId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/mfa/setup",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_mfa.verify",
"title": "Verify user MFA setup",
"description": "Verify a TOTP code and enable MFA for one user.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/mfa/verify",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Verify user MFA setup.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"token": "example",
"setupToken": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/mfa/verify",
"body": {
"userId": "example",
"token": "example",
"setupToken": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/mfa/verify",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_mfa.disable",
"title": "Disable user MFA",
"description": "Disable MFA for one visible user.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}/mfa",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Disable user MFA.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example/mfa",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*/mfa",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_mfa.backup_codes.regenerate",
"title": "Regenerate user backup codes",
"description": "Replace and return the one-time backup codes for an MFA-enabled user.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/backup-codes",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Regenerate user backup codes.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/backup-codes",
"body": {
"userId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/backup-codes",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_passkeys.registration.begin",
"title": "Begin passkey registration",
"description": "Create WebAuthn registration options for one user.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/passkeys/setup",
"permission": "users:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Begin passkey registration.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/passkeys/setup",
"body": {
"userId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/passkeys/setup",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_passkeys.registration.complete",
"title": "Complete passkey registration",
"description": "Verify and store a WebAuthn credential for one user.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/passkeys/verify",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Complete passkey registration.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"credential": {},
"challengeId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/passkeys/verify",
"body": {
"userId": "example",
"credential": {},
"challengeId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/passkeys/verify",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_passkeys.list",
"title": "List user passkeys",
"description": "List sanitized passkey credentials for one visible user.",
"target": "api",
"method": "GET",
"path": "/api/users/{userId}/passkeys",
"permission": "users:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"userId": {
"type": "string",
"minLength": 1
}
},
"required": [
"userId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List user passkeys.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/users/example/passkeys",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/users/*/passkeys",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_passkeys.delete",
"title": "Delete user passkey",
"description": "Delete one passkey credential belonging to a visible user.",
"target": "api",
"method": "DELETE",
"path": "/api/users/{userId}/passkeys/{passkeyId}",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete user passkey.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"passkeyId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/users/example/passkeys/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/users/*/passkeys/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_password.change",
"title": "Change my password",
"description": "Change the caller's password after verifying their current password.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/password",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Change my password.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"currentPassword": "examplex",
"newPassword": "examplex"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/password",
"body": {
"userId": "example",
"currentPassword": "examplex",
"newPassword": "examplex"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/password",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_password.set_initial",
"title": "Set my initial password",
"description": "Establish the caller's first password for a passwordless account.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/password/initial",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Set my initial password.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"newPassword": "examplex"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/password/initial",
"body": {
"userId": "example",
"newPassword": "examplex"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/password/initial",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "user_password.admin_reset",
"title": "Reset user password",
"description": "Set a new password for one user managed by the caller.",
"target": "api",
"method": "POST",
"path": "/api/users/{userId}/password/admin-reset",
"permission": "users:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Reset user password.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"userId": "example",
"newPassword": "examplex"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/users/example/password/admin-reset",
"body": {
"userId": "example",
"newPassword": "examplex"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/users/*/password/admin-reset",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "api_keys.options",
"title": "Get API key options",
"description": "List the applications scopes and resources the caller may bind to a new API key.",
"target": "api",
"method": "GET",
"path": "/api/api-keys/options",
"permission": "api_keys:read",
"inputSchema": {
"$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
},
"outputSchema": {
"$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
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/api-keys/",
"resource": {
"kind": "api_key_options",
"idPath": "data.appId"
},
"effects": [
"Returns only applications scopes and resources currently available to the authenticated caller."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the application or organization identifier and retry."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use an application and organization visible to the authenticated caller."
}
],
"verify": [
"Use the returned allowedScopes without widening them before planning api_keys.create."
],
"nextActionIds": [
"app_topolo_auth.api_keys.create"
]
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/api-keys/options",
"body": null
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/api-keys/",
"resource": {
"kind": "api_key_options",
"idPath": "data.appId"
},
"next_action_ids": [
"app_topolo_auth.api_keys.create"
],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/api-keys/options",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "api_keys.list",
"title": "List API keys",
"description": "List central API keys visible to the caller.",
"target": "api",
"method": "GET",
"path": "/api/api-keys",
"permission": "api_keys:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"organizationId": {
"type": "string",
"minLength": 1
},
"appId": {
"type": "string",
"minLength": 1
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List API keys.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"organizationId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/api-keys",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/api-keys",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "api_keys.create",
"title": "Create API key",
"description": "Create a credential scoped to one organization, application, permission set, and optional resources.",
"target": "api",
"method": "POST",
"path": "/api/api-keys",
"permission": "api_keys:write",
"inputSchema": {
"$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
},
"outputSchema": {
"$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
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"agentContract": {
"docsUrl": "https://docs.topolo.app/platform/api-keys/",
"resource": {
"kind": "api_key",
"idPath": "data.key.id"
},
"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."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the reported field using the published input schema and retry."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use an authorized organization, application, scope, and resource selection; do not widen access automatically."
},
{
"status": 500,
"code": "SERVER_ERROR",
"recovery": "Preserve the request id and retry only after the platform error is resolved."
}
],
"verify": [
"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."
],
"rollbackActionId": "app_topolo_auth.api_keys.revoke",
"nextActionIds": [
"app_topolo_auth.api_keys.list"
],
"examples": [
{
"appId": "app_topolo_campaigns",
"name": "Staging demo agent",
"scopes": [
"workspaces:read"
]
}
]
},
"documentation": {
"example_input": {
"appId": "app_topolo_campaigns",
"name": "Staging demo agent",
"scopes": [
"workspaces:read"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/api-keys",
"body": {
"appId": "app_topolo_campaigns",
"name": "Staging demo agent",
"scopes": [
"workspaces:read"
]
}
},
"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."
],
"docs_url": "https://docs.topolo.app/platform/api-keys/",
"resource": {
"kind": "api_key",
"idPath": "data.key.id"
},
"next_action_ids": [
"app_topolo_auth.api_keys.list"
],
"rollback_action_id": "app_topolo_auth.api_keys.revoke"
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/api-keys",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "api_keys.update",
"title": "Update API key",
"description": "Update the name, scopes, resource bindings, or expiry of one API key.",
"target": "api",
"method": "PUT",
"path": "/api/api-keys/{apiKeyId}",
"permission": "api_keys:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update API key.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"apiKeyId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/api-keys/example",
"body": {
"apiKeyId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/api-keys/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "api_keys.revoke",
"title": "Revoke API key",
"description": "Revoke one central API key.",
"target": "api",
"method": "POST",
"path": "/api/api-keys/{apiKeyId}/revoke",
"permission": "api_keys:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"apiKeyId": {
"type": "string",
"minLength": 1
}
},
"required": [
"apiKeyId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke API key.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"apiKeyId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/api-keys/example/revoke",
"body": {
"apiKeyId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/api-keys/*/revoke",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sso_exchange_diagnostics.list",
"title": "List SSO exchange diagnostics",
"description": "Inspect sanitized handoff-to-exchange timing, replay outcomes, failures, and request correlation within the caller-visible organization.",
"target": "api",
"method": "GET",
"path": "/api/sso/exchange-diagnostics",
"permission": "sessions:read",
"inputSchema": {
"$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
},
"outputSchema": {
"$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
},
"agentContract": {
"docsUrl": "https://docs.topolo.app/internal/platform/auth-and-identity/",
"resource": {
"kind": "sso_exchange_diagnostic",
"idPath": "data.exchanges[].exchangeId"
},
"effects": [
"Reads a seven-day sanitized exchange diagnostic ledger without returning codes, hashes, tokens, redirect paths, or cached user payloads."
],
"errors": [
{
"status": 400,
"code": "VALIDATION_ERROR",
"recovery": "Correct the closed filter schema or time range and retry."
},
{
"status": 401,
"code": "AUTH_ERROR",
"recovery": "Refresh the caller session or credential before retrying."
},
{
"status": 403,
"code": "FORBIDDEN",
"recovery": "Use sessions:read within the active organization; do not widen the requested tenant."
}
],
"verify": [
"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."
],
"examples": [
{
"organizationId": "org_acme",
"requestId": "3f9c867d-0c1e-4ec7-9aaf-8f74be533b61",
"limit": 25
}
],
"recovery": "Narrow by organization, application, request ID, outcome, or time window; diagnostics older than seven days are intentionally unavailable."
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"organizationId": "org_acme",
"requestId": "3f9c867d-0c1e-4ec7-9aaf-8f74be533b61",
"limit": 25
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/sso/exchange-diagnostics",
"body": null
},
"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."
],
"docs_url": "https://docs.topolo.app/internal/platform/auth-and-identity/",
"resource": {
"kind": "sso_exchange_diagnostic",
"idPath": "data.exchanges[].exchangeId"
},
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/sso/exchange-diagnostics",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "admin.stats",
"title": "Get Auth admin stats",
"description": "Read Auth admin dashboard statistics.",
"method": "GET",
"path": "/api/admin/stats",
"permission": "audit:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get Auth admin stats.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/stats",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/admin/stats",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "admin.system_health",
"title": "Get Auth system health",
"description": "Read Auth system health status.",
"method": "GET",
"path": "/api/admin/system-health",
"permission": "audit:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get Auth system health.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"limit": 1,
"cursor": "app_topolo_example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/system-health",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/admin/system-health",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "audit_logs.list",
"title": "List audit logs",
"description": "Read Auth audit log entries.",
"method": "GET",
"path": "/api/audit-logs",
"permission": "audit:read",
"readOnly": true,
"target": "api",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List audit logs.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"action": "example",
"organization": "example",
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/audit-logs",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/audit-logs",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "admin.recent_activity",
"title": "Get recent Auth activity",
"description": "Read recent activity recorded by the Auth control plane.",
"target": "api",
"method": "GET",
"path": "/api/admin/recent-activity",
"permission": "audit:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get recent Auth activity.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/admin/recent-activity",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/admin/recent-activity",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "services.list",
"title": "List services",
"description": "List services registered with the Auth control plane.",
"target": "api",
"method": "GET",
"path": "/api/services",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List services.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"cursor": "app_topolo_example",
"limit": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "services.get",
"title": "Get service",
"description": "Read one registered service by canonical application id.",
"target": "api",
"method": "GET",
"path": "/api/services/{appId}",
"permission": "services:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get service.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "services.create",
"title": "Create service",
"description": "Create a platform-managed service registration.",
"target": "api",
"method": "POST",
"path": "/api/services",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create service.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"name": "example",
"base_url": "https://example.com"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/services",
"body": {
"name": "example",
"base_url": "https://example.com"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/services",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "services.update",
"title": "Update service",
"description": "Update a platform-managed service registration.",
"target": "api",
"method": "PUT",
"path": "/api/services/{appId}",
"permission": "services:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update service.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/services/example",
"body": {
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/services/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "services.delete",
"title": "Delete service",
"description": "Delete a platform-managed service registration.",
"target": "api",
"method": "DELETE",
"path": "/api/services/{appId}",
"permission": "services:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete service.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/services/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/services/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_permissions.list",
"title": "List service permissions",
"description": "List permissions declared by one service.",
"target": "api",
"method": "GET",
"path": "/api/services/{appId}/permissions",
"permission": "permissions:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List service permissions.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services/example/permissions",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services/*/permissions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_api_key_scopes.list",
"title": "List service API key scopes",
"description": "List API key scopes exposed by one service.",
"target": "api",
"method": "GET",
"path": "/api/services/{appId}/api-key-scopes",
"permission": "permissions:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List service API key scopes.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services/example/api-key-scopes",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services/*/api-key-scopes",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_api_key_resources.list",
"title": "List service API key resources",
"description": "List credential-bindable resources exposed by one service.",
"target": "api",
"method": "GET",
"path": "/api/services/{appId}/api-key-resources",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List service API key resources.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"authorizationMode": "runtime",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services/example/api-key-resources",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services/*/api-key-resources",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_permissions.create",
"title": "Create service permission",
"description": "Create a permission for one platform-managed service.",
"target": "api",
"method": "POST",
"path": "/api/services/{appId}/permissions",
"permission": "permissions:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create service permission.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example",
"name": "2026-01-01"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/services/example/permissions",
"body": {
"appId": "example",
"name": "2026-01-01"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/services/*/permissions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_permissions.update",
"title": "Update service permission",
"description": "Update one service permission.",
"target": "api",
"method": "PUT",
"path": "/api/permissions/{permissionId}",
"permission": "permissions:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Update service permission.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"permissionId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/permissions/example",
"body": {
"permissionId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_permissions.delete",
"title": "Delete service permission",
"description": "Delete one service permission.",
"target": "api",
"method": "DELETE",
"path": "/api/permissions/{permissionId}",
"permission": "permissions:write",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"permissionId": {
"type": "string",
"minLength": 1
}
},
"required": [
"permissionId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete service permission.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"permissionId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/permissions/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_role_permissions.get",
"title": "Get service role permissions",
"description": "Read a service role permission bundle.",
"target": "api",
"method": "GET",
"path": "/api/services/{appId}/role-permissions/{role}",
"permission": "roles:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get service role permissions.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example",
"role": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services/example/role-permissions/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services/*/role-permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_role_permissions.replace",
"title": "Replace service role permissions",
"description": "Replace the permission bundle for a service role.",
"target": "api",
"method": "PUT",
"path": "/api/services/{appId}/role-permissions/{role}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Replace service role permissions.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example",
"role": "example",
"permissions": [
"example"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/services/example/role-permissions/example",
"body": {
"appId": "example",
"role": "example",
"permissions": [
"example"
]
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/services/*/role-permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_role_permissions.add",
"title": "Add service role permission",
"description": "Add one permission to a service role.",
"target": "api",
"method": "POST",
"path": "/api/services/{appId}/role-permissions/{role}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Add service role permission.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example",
"role": "example",
"permission": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/services/example/role-permissions/example",
"body": {
"appId": "example",
"role": "example",
"permission": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/services/*/role-permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_role_permissions.remove",
"title": "Remove service role permission",
"description": "Remove one permission from a service role.",
"target": "api",
"method": "DELETE",
"path": "/api/services/{appId}/role-permissions/{role}/{permission}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Remove service role permission.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "example",
"role": "example",
"permission": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/services/example/role-permissions/example/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/services/*/role-permissions/*/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_roles.list",
"title": "List declared service roles",
"description": "List the operator roles declared by one service.",
"target": "api",
"method": "GET",
"path": "/api/services/{appId}/declared-roles",
"permission": "roles:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"appId": {
"type": "string",
"minLength": 1
}
},
"required": [
"appId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List declared service roles.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/services/example/declared-roles",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/services/*/declared-roles",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_roles.list",
"title": "List organization roles",
"description": "List roles defined for one organization.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/roles",
"permission": "roles:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List organization roles.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/roles",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/roles",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_roles.create",
"title": "Create organization role",
"description": "Create a custom role for one organization.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/roles",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Create organization role.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/roles",
"body": {
"orgId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/roles",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_roles.delete",
"title": "Delete organization role",
"description": "Delete one custom organization role.",
"target": "api",
"method": "DELETE",
"path": "/api/organizations/{orgId}/roles/{roleKey}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Delete organization role.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"roleKey": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/organizations/example/roles/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/organizations/*/roles/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_services.install",
"title": "Install organization service",
"description": "Install or update access to an application for one organization.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/services/{appId}/install",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Install organization service.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/services/example/install",
"body": {
"orgId": "example",
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/services/*/install",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_seats.get",
"title": "Get organization seat summary",
"description": "Read seat pools and usage across an organization.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/seats",
"permission": "organizations:read",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"orgId": {
"type": "string",
"minLength": 1
}
},
"required": [
"orgId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get organization seat summary.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/seats",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/seats",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_seats.get",
"title": "Get service seats",
"description": "Read one service seat pool and its assignees.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/services/{appId}/seats",
"permission": "organizations:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get service seats.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/services/example/seats",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/services/*/seats",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_seats.assign",
"title": "Assign service seat",
"description": "Assign an application seat to an organization member.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/services/{appId}/seats/assign",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Assign service seat.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/services/example/seats/assign",
"body": {
"orgId": "example",
"appId": "example",
"userId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/services/*/seats/assign",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_seats.revoke",
"title": "Revoke service seat",
"description": "Revoke an application seat from an organization member.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/services/{appId}/seats/revoke",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Revoke service seat.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"userId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/services/example/seats/revoke",
"body": {
"orgId": "example",
"appId": "example",
"userId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/services/*/seats/revoke",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "service_seats.reseat",
"title": "Reassign service seat",
"description": "Move an application seat between organization members.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/services/{appId}/seats/reseat",
"permission": "organizations:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Reassign service seat.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"fromUserId": "example",
"toUserId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/services/example/seats/reseat",
"body": {
"orgId": "example",
"appId": "example",
"fromUserId": "example",
"toUserId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/services/*/seats/reseat",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_services.request_access",
"title": "Request service access",
"description": "Request access to an application from organization administrators.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/services/{appId}/access-request",
"permission": "services:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Request service access.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/services/example/access-request",
"body": {
"orgId": "example",
"appId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/services/*/access-request",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_role_permissions.get",
"title": "Get organization role permissions",
"description": "Read one organization role permission bundle for an application.",
"target": "api",
"method": "GET",
"path": "/api/organizations/{orgId}/services/{appId}/role-permissions/{role}",
"permission": "roles:read",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get organization role permissions.",
"additionalProperties": true
},
"readOnly": true,
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"role": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/organizations/example/services/example/role-permissions/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/organizations/*/services/*/role-permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_role_permissions.replace",
"title": "Replace organization role permissions",
"description": "Replace one organization role permission bundle for an application.",
"target": "api",
"method": "PUT",
"path": "/api/organizations/{orgId}/services/{appId}/role-permissions/{role}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Replace organization role permissions.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"role": "example",
"permissions": [
"example"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/organizations/example/services/example/role-permissions/example",
"body": {
"orgId": "example",
"appId": "example",
"role": "example",
"permissions": [
"example"
]
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/organizations/*/services/*/role-permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_role_permissions.add",
"title": "Add organization role permission",
"description": "Add one application permission to an organization role.",
"target": "api",
"method": "POST",
"path": "/api/organizations/{orgId}/services/{appId}/role-permissions/{role}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Add organization role permission.",
"additionalProperties": true
},
"readOnly": false,
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"role": "example",
"permission": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/organizations/example/services/example/role-permissions/example",
"body": {
"orgId": "example",
"appId": "example",
"role": "example",
"permission": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/organizations/*/services/*/role-permissions/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "organization_role_permissions.remove",
"title": "Remove organization role permission",
"description": "Remove one application permission from an organization role.",
"target": "api",
"method": "DELETE",
"path": "/api/organizations/{orgId}/services/{appId}/role-permissions/{role}/{permission}",
"permission": "roles:write",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Remove organization role permission.",
"additionalProperties": true
},
"readOnly": false,
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"orgId": "example",
"appId": "example",
"role": "example",
"permission": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/organizations/example/services/example/role-permissions/example/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/organizations/*/services/*/role-permissions/*/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
}
],
"action_coverage": {
"status": "ok",
"served_routes": 276,
"matched_actions": 181,
"declared_unserved_actions": [],
"coverage_excluded_actions": [],
"uncatalogued_routes": [
{
"key": "GET /favicon.svg",
"method": "GET",
"path": "/favicon.svg",
"source": "src/auth-core-routes.js",
"target": "api"
},
{
"key": "POST /api/surface-launches",
"method": "POST",
"path": "/api/surface-launches",
"source": "src/auth-core-routes.js",
"target": "api"
},
{
"key": "POST /api/surface-sessions",
"method": "POST",
"path": "/api/surface-sessions",
"source": "src/auth-core-routes.js",
"target": "api"
},
{
"key": "POST /internal/platform/encryption/master-key/rewrap",
"method": "POST",
"path": "/internal/platform/encryption/master-key/rewrap",
"source": "src/index.js",
"target": "api"
}
],
"ignored_routes": 91,
"configured_exclusions": 52,
"configuration_findings": [],
"notes": []
},
"runtime_contract_audit": {
"status": "verified",
"actions": 181,
"contracts": 181,
"contract_module": "topolo.action-contracts.mjs",
"validator_sources": [
"src/index.js"
],
"authorization_sources": [
"src/index.js"
],
"findings": []
}
},
{
"source_path": "topolo-platform/core/TopoloCloudControl/topolo.app.json",
"service_slug": "topolo-platform",
"name": "cloudcontrol",
"app_id": null,
"compatibility_date": null,
"primary_target": null,
"environments": [],
"targets": [
{
"name": "deploy",
"kind": "cron",
"directory": ".",
"main": "staging-activity-worker/wrangler.jsonc",
"worker_name": null,
"subdomain": null,
"healthcheck_path": null,
"variable_names": [],
"secret_names": [],
"bindings": []
}
],
"notifications": [],
"notification_contract": {
"source_path": null,
"role": "internal_non_producer",
"schema_version": null,
"owner_app_id": null,
"events": []
},
"actions": [],
"action_coverage": {
"status": "n/a",
"served_routes": 0,
"matched_actions": 0,
"declared_unserved_actions": [],
"coverage_excluded_actions": [],
"uncatalogued_routes": [],
"ignored_routes": 0,
"configured_exclusions": 0,
"configuration_findings": [],
"notes": []
},
"runtime_contract_audit": {
"status": "verified",
"actions": 0,
"contracts": 0,
"contract_module": null,
"validator_sources": [],
"authorization_sources": [],
"findings": []
}
},
{
"source_path": "system-apps/TopoloDocs/topolo.app.json",
"service_slug": "topolo-platform",
"name": "topolo-docs",
"app_id": "app_topolo_docs",
"compatibility_date": "2026-05-01",
"primary_target": "web",
"environments": [
"development",
"production",
"staging"
],
"targets": [
{
"name": "api",
"kind": "worker",
"directory": "apps/api",
"main": "src/worker.ts",
"worker_name": "topolo-docs-api",
"subdomain": null,
"healthcheck_path": "/health",
"variable_names": [
"APP_ID",
"AUTH_API_URL",
"AUTH_ORIGIN",
"DOCS_PUBLIC_BASE_URL",
"ENVIRONMENT",
"NEXUS_GATEWAY_URL",
"TOPOLO_NOTIFY_URL",
"VITE_TOPOLO_APP_ID"
],
"secret_names": [],
"bindings": [
{
"kind": "d1",
"binding": "DOCS_CONTROL_DB",
"target": null
},
{
"kind": "d1",
"binding": "DOCS_CONTENT_DB",
"target": null
},
{
"kind": "d1",
"binding": "DOCS_OPERATIONS_DB",
"target": null
},
{
"kind": "r2",
"binding": "DOCS_PUBLICATIONS",
"target": null
},
{
"kind": "kv",
"binding": "DOCS_PUBLISHED_KV",
"target": null
}
]
},
{
"name": "web",
"kind": "worker",
"directory": "apps/web",
"main": "src/worker.ts",
"worker_name": "topolo-docs",
"subdomain": "docs",
"healthcheck_path": "/health",
"variable_names": [
"AUTH_API_URL",
"AUTH_ORIGIN",
"ENVIRONMENT",
"INSIGHTS_SITE_KEY"
],
"secret_names": [],
"bindings": [
{
"kind": "services",
"binding": "API",
"target": null
}
]
}
],
"notifications": [
"docs.catalog.drift_detected",
"docs.link_check.failed",
"docs.publish.completed",
"docs.publish.failed"
],
"notification_contract": {
"source_path": "topolo.notification-contracts.json",
"role": "producer",
"schema_version": 1,
"owner_app_id": "app_topolo_docs",
"events": [
{
"type": "docs.catalog.drift_detected",
"version": 1,
"description": "A persisted Docs catalog validation run detected a source digest mismatch.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"source",
"expected_digest",
"actual_digest",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"source": {
"type": "string",
"minLength": 1
},
"expected_digest": {
"type": "string",
"minLength": 1
},
"actual_digest": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Documentation catalog drift detected",
"body": "Auth permissions no longer match their published documentation catalog.",
"object_id": "docsrun_123",
"source": "Auth permissions",
"expected_digest": "sha256:expected",
"actual_digest": "sha256:actual",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"sensitiveFields": [],
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^docs:catalog-drift-detected:"
}
},
{
"type": "docs.link_check.failed",
"version": 1,
"description": "A persisted Docs link validation run recorded an unreachable documentation URL.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"checked_url",
"status_code",
"reason",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"checked_url": {
"type": "string",
"format": "uri"
},
"status_code": {
"type": [
"integer",
"null"
],
"minimum": 100,
"maximum": 599
},
"reason": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Documentation link check failed",
"body": "https://docs.stg.topolo.us/reference/missing failed documentation link validation.",
"object_id": "docsrun_124",
"checked_url": "https://docs.stg.topolo.us/reference/missing",
"status_code": 404,
"reason": "Expected a successful response.",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"sensitiveFields": [],
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^docs:link-check-failed:"
}
},
{
"type": "docs.publish.completed",
"version": 1,
"description": "A documentation revision was durably recorded as published to an environment.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"revision",
"environment",
"published_url",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"revision": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"enum": [
"development",
"staging",
"production"
]
},
"published_url": {
"type": "string",
"format": "uri"
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Documentation publish completed",
"body": "abc123 was published to staging.",
"object_id": "docsrun_125",
"revision": "abc123",
"environment": "staging",
"published_url": "https://docs.stg.topolo.us",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"sensitiveFields": [],
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^docs:publish-completed:"
}
},
{
"type": "docs.publish.failed",
"version": 1,
"description": "A documentation revision was durably recorded as failed during publication.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"revision",
"environment",
"reason",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"object_id": {
"type": "string",
"minLength": 1
},
"revision": {
"type": "string",
"minLength": 1
},
"environment": {
"type": "string",
"enum": [
"development",
"staging",
"production"
]
},
"reason": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Documentation publish failed",
"body": "abc124 failed to publish to staging.",
"object_id": "docsrun_126",
"revision": "abc124",
"environment": "staging",
"reason": "The publication validation gate failed.",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"sensitiveFields": [],
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^docs:publish-failed:"
}
}
]
},
"actions": [
{
"name": "widget.get",
"title": "Get widget summary",
"description": "Get the TopoloOne widget summary for Docs.",
"method": "GET",
"path": "/api/widget",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/widget",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/widget",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace.bootstrap",
"title": "Get application bootstrap",
"description": "Get the authenticated Docs user and organization context.",
"method": "GET",
"path": "/api/bootstrap",
"permission": "workspace:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/bootstrap",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/bootstrap",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace.get",
"title": "Get Docs workspace",
"description": "Get the active Docs workspace projection.",
"method": "GET",
"path": "/api/docs/workspace",
"permission": "workspace:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/workspace",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/workspace",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspaces.archive",
"title": "Archive Docs workspace",
"description": "Archive an empty Docs workspace and purge its archived Docs data.",
"method": "DELETE",
"path": "/api/docs/workspaces/{workspaceId}",
"permission": "workspace:delete",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"workspaceId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"workspaceId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"workspaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/docs/workspaces/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/docs/workspaces/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.list",
"title": "List documentation spaces",
"description": "List active documentation spaces in the selected workspace.",
"method": "GET",
"path": "/api/docs/spaces",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/spaces",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/spaces",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.create",
"title": "Create documentation space",
"description": "Create a tenant-isolated documentation space.",
"method": "POST",
"path": "/api/docs/spaces",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"title": "example",
"slug": "example",
"description": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/spaces",
"body": {
"title": "example",
"slug": "example",
"description": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/spaces",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.get",
"title": "Get documentation space",
"description": "Get one documentation space from the selected workspace.",
"method": "GET",
"path": "/api/docs/spaces/{spaceId}",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"spaceId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"spaceId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"spaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/spaces/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/spaces/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.update",
"title": "Update documentation space",
"description": "Update a documentation space, visibility, locale, or brand configuration.",
"method": "PATCH",
"path": "/api/docs/spaces/{spaceId}",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"spaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PATCH",
"path": "/api/docs/spaces/example",
"body": {
"spaceId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PATCH /api/docs/spaces/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.archive",
"title": "Archive documentation space",
"description": "Archive a documentation space and remove it from active workspace navigation.",
"method": "DELETE",
"path": "/api/docs/spaces/{spaceId}",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"spaceId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"spaceId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"spaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/docs/spaces/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/docs/spaces/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.documents.list",
"title": "List space documents",
"description": "List active documents in one documentation space.",
"method": "GET",
"path": "/api/docs/spaces/{spaceId}/documents",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"spaceId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"spaceId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"spaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/spaces/example/documents",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/spaces/*/documents",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.documents.create",
"title": "Create document",
"description": "Create a document and its first immutable locale version.",
"method": "POST",
"path": "/api/docs/spaces/{spaceId}/documents",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"spaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/spaces/example/documents",
"body": {
"spaceId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/spaces/*/documents",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.sections.list",
"title": "List space sections",
"description": "List the configurable top-level sections a documentation space is organized into.",
"method": "GET",
"path": "/api/docs/spaces/{spaceId}/sections",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"spaceId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"spaceId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"spaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/spaces/example/sections",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/spaces/*/sections",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.sections.create",
"title": "Create section",
"description": "Create a top-level navigation section in one documentation space.",
"method": "POST",
"path": "/api/docs/spaces/{spaceId}/sections",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"spaceId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/spaces/example/sections",
"body": {
"spaceId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/spaces/*/sections",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "spaces.sections.reorder",
"title": "Reorder space sections",
"description": "Set the display order of every section in one documentation space.",
"method": "POST",
"path": "/api/docs/spaces/{spaceId}/sections/reorder",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"agentContract": {
"docsUrl": "https://docs.topolo.app/applications/docs",
"resource": {
"kind": "documentation_section_order",
"idPath": "$.spaceId"
},
"effects": [
"Replaces the complete section display order for one documentation space."
],
"errors": [
{
"status": 400,
"code": "invalid_section_order",
"recovery": "List the space sections and submit every section id exactly once."
},
{
"status": 403,
"code": "forbidden",
"recovery": "Use a credential with docs:write access to the selected Docs workspace."
}
],
"verify": [
"Call spaces.sections.list for the same spaceId and confirm the returned section order matches sectionIds."
],
"examples": [
{
"input": {
"spaceId": "space_example",
"sectionIds": [
"section_intro",
"section_reference"
]
},
"expected": "The space sections are returned in the requested display order."
}
]
},
"documentation": {
"example_input": {
"spaceId": "space_example",
"sectionIds": [
"section_intro",
"section_reference"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/spaces/space_example/sections/reorder",
"body": {
"spaceId": "space_example",
"sectionIds": [
"section_intro",
"section_reference"
]
}
},
"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."
],
"docs_url": "https://docs.topolo.app/applications/docs",
"resource": {
"kind": "documentation_section_order",
"idPath": "$.spaceId"
},
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/spaces/*/sections/reorder",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sections.update",
"title": "Rename section",
"description": "Rename a documentation section or change its slug.",
"method": "PATCH",
"path": "/api/docs/sections/{sectionId}",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"sectionId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PATCH",
"path": "/api/docs/sections/example",
"body": {
"sectionId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PATCH /api/docs/sections/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sections.delete",
"title": "Delete section",
"description": "Delete a documentation section; its documents become unassigned rather than being deleted.",
"method": "DELETE",
"path": "/api/docs/sections/{sectionId}",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"sectionId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"sectionId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"sectionId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/docs/sections/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/docs/sections/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.section.set",
"title": "File document into a section",
"description": "Move a document into a section of its space, or unassign it, and set its position within that section.",
"method": "PUT",
"path": "/api/docs/documents/{documentId}/section",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"documentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/docs/documents/example/section",
"body": {
"documentId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/docs/documents/*/section",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.list",
"title": "List workspace documents",
"description": "List active documents across the selected workspace.",
"method": "GET",
"path": "/api/docs/documents",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/documents",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/documents",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.get",
"title": "Get document",
"description": "Get one document and its immutable version history.",
"method": "GET",
"path": "/api/docs/documents/{documentId}",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"documentId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"documentId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"documentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/documents/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/documents/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.update",
"title": "Update document metadata",
"description": "Update native document metadata and review state.",
"method": "PATCH",
"path": "/api/docs/documents/{documentId}",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"documentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PATCH",
"path": "/api/docs/documents/example",
"body": {
"documentId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PATCH /api/docs/documents/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.archive",
"title": "Archive document",
"description": "Archive a native document and remove its publication pointer.",
"method": "DELETE",
"path": "/api/docs/documents/{documentId}",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"documentId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"documentId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"documentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "DELETE",
"path": "/api/docs/documents/example",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "DELETE /api/docs/documents/*",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.versions.list",
"title": "List document versions",
"description": "List immutable versions for one document.",
"method": "GET",
"path": "/api/docs/documents/{documentId}/versions",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"documentId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"documentId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"documentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/documents/example/versions",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/documents/*/versions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.versions.create",
"title": "Create document version",
"description": "Create an immutable locale-specific version and update full-text retrieval.",
"method": "POST",
"path": "/api/docs/documents/{documentId}/versions",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"documentId": "example",
"bodyMarkdown": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/documents/example/versions",
"body": {
"documentId": "example",
"bodyMarkdown": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/documents/*/versions",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.publish",
"title": "Publish document version",
"description": "Publish one exact document version as an immutable public snapshot.",
"method": "POST",
"path": "/api/docs/documents/{documentId}/publish",
"permission": "docs:publish",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"documentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/documents/example/publish",
"body": {
"documentId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/documents/*/publish",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "documents.unpublish",
"title": "Unpublish document",
"description": "Remove public lookup pointers for a document.",
"method": "POST",
"path": "/api/docs/documents/{documentId}/unpublish",
"permission": "docs:publish",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"documentId": {
"type": "string",
"minLength": 1,
"maxLength": 160
}
},
"required": [
"documentId"
],
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": true,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"documentId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/documents/example/unpublish",
"body": {
"documentId": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/documents/*/unpublish",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "search.query",
"title": "Search workspace documents",
"description": "Run tenant-filtered full-text search across current locale versions.",
"method": "GET",
"path": "/api/docs/search",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"q": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/search",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/search",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "public_search.query",
"title": "Search a published documentation space",
"description": "Search titles, summaries, and published body text in one public documentation space. Anonymous; only published versions are matched.",
"method": "GET",
"path": "/api/public/docs/{spaceSlug}/search.json",
"authorizationMode": "public",
"readOnly": true,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"spaceSlug": "example",
"q": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/public/docs/example/search.json",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/public/docs/*/search.json",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "search.ask",
"title": "Ask workspace documentation",
"description": "Answer from tenant-filtered retrieved versions and return immutable citations.",
"method": "POST",
"path": "/api/docs/ask",
"permission": "docs:read",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"query": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/ask",
"body": {
"query": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/ask",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "workspace.export",
"title": "Export workspace documentation",
"description": "Export spaces, documents, versions, and publication metadata for the selected workspace.",
"method": "GET",
"path": "/api/docs/export",
"permission": "docs:export",
"authorizationMode": "static",
"readOnly": true,
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/docs/export",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/docs/export",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "platform_corpus.sync",
"title": "Sync canonical platform documentation",
"description": "Project the revisioned Topolo platform corpus into its platform-owned Docs workspace in an idempotent batch.",
"method": "POST",
"path": "/api/docs/platform-corpus/sync",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"cursor": 1,
"limit": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/docs/platform-corpus/sync",
"body": {
"cursor": 1,
"limit": 1
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/docs/platform-corpus/sync",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "operations.catalog_drift.record",
"title": "Record documentation catalog drift",
"description": "Persist a catalog drift result and notify the platform operator.",
"method": "POST",
"path": "/api/operations/catalog-drift",
"permission": "validation:invoke",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"runId": "example",
"source": "example",
"expectedDigest": "example",
"actualDigest": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/operations/catalog-drift",
"body": {
"runId": "example",
"source": "example",
"expectedDigest": "example",
"actualDigest": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/operations/catalog-drift",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "operations.link_checks.fail",
"title": "Record failed documentation link check",
"description": "Persist a failed link validation result and notify the platform operator.",
"method": "POST",
"path": "/api/operations/link-checks/failed",
"permission": "validation:invoke",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"runId": "example",
"checkedUrl": "https://example.com",
"reason": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/operations/link-checks/failed",
"body": {
"runId": "example",
"checkedUrl": "https://example.com",
"reason": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/operations/link-checks/failed",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "operations.publishes.complete",
"title": "Record completed documentation publish",
"description": "Persist a completed documentation publish and notify the platform operator.",
"method": "POST",
"path": "/api/operations/publishes/completed",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"runId": "example",
"revision": "example",
"environment": "development",
"publishedUrl": "https://example.com"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/operations/publishes/completed",
"body": {
"runId": "example",
"revision": "example",
"environment": "development",
"publishedUrl": "https://example.com"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/operations/publishes/completed",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "operations.publishes.fail",
"title": "Record failed documentation publish",
"description": "Persist a failed documentation publish and notify the platform operator.",
"method": "POST",
"path": "/api/operations/publishes/failed",
"permission": "docs:write",
"authorizationMode": "static",
"readOnly": false,
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"target": "api",
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"runId": "example",
"revision": "example",
"environment": "development",
"reason": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/operations/publishes/failed",
"body": {
"runId": "example",
"revision": "example",
"environment": "development",
"reason": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/operations/publishes/failed",
"evidence": "Matched to a served route extracted from canonical staging source."
}
}
],
"action_coverage": {
"status": "ok",
"served_routes": 40,
"matched_actions": 34,
"declared_unserved_actions": [],
"coverage_excluded_actions": [],
"uncatalogued_routes": [],
"ignored_routes": 6,
"configured_exclusions": 3,
"configuration_findings": [],
"notes": [
"5 manually-declared route(s)"
]
},
"runtime_contract_audit": {
"status": "verified",
"actions": 34,
"contracts": 34,
"contract_module": "topolo.action-contracts.mjs",
"validator_sources": [
"apps/api/src/worker.ts"
],
"authorization_sources": [
"apps/api/src/worker.ts"
],
"findings": []
}
},
{
"source_path": "topolo-platform/services/TopoloLocalize/topolo.app.json",
"service_slug": "topolo-platform",
"name": "topolo-localize",
"app_id": "app_topolo_localize",
"compatibility_date": "2026-07-06",
"primary_target": "web",
"environments": [
"development",
"production",
"staging"
],
"targets": [
{
"name": "web",
"kind": "worker",
"directory": ".",
"main": "src/index.js",
"worker_name": "topolo-localize",
"subdomain": "localize",
"healthcheck_path": "/health",
"variable_names": [],
"secret_names": [],
"bindings": []
}
],
"notifications": [
"localize.catalog.published",
"localize.missing_keys.detected",
"localize.review.requested",
"localize.source.drift_detected",
"localize.translation.completed",
"localize.translation.failed"
],
"notification_contract": {
"source_path": "topolo.notification-contracts.json",
"role": "producer",
"schema_version": 1,
"owner_app_id": "app_topolo_localize",
"events": [
{
"type": "localize.catalog.published",
"version": 1,
"description": "A versioned translation catalog was persisted and published to the immutable catalog store.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"app_id",
"namespace",
"locale",
"version",
"key_count",
"url",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"category": {
"const": "localize"
},
"severity": {
"const": "success"
},
"object_type": {
"const": "translation_catalog"
},
"object_id": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"namespace": {
"type": "string",
"minLength": 1
},
"locale": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"key_count": {
"type": "integer",
"minimum": 0
},
"url": {
"type": "string",
"format": "uri"
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Catalog published for app_topolo_forms",
"body": "app_topolo_forms/common/ar v42 was published with 180 keys.",
"category": "localize",
"severity": "success",
"object_type": "translation_catalog",
"object_id": "app_topolo_forms:common:ar:v42",
"app_id": "app_topolo_forms",
"namespace": "common",
"locale": "ar",
"version": "v42",
"key_count": 180,
"url": "https://localize.stg.topolo.us/catalogs/app_topolo_forms/ar/common.v42.json",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^localize:catalog:"
},
"sensitiveFields": []
},
{
"type": "localize.missing_keys.detected",
"version": 1,
"description": "A durable catalog scan found source keys without values for one target locale.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"app_id",
"namespace",
"locale",
"missing_count",
"source_count",
"missing_keys",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"category": {
"const": "localize"
},
"severity": {
"const": "warning"
},
"object_type": {
"const": "translation_missing_keys"
},
"object_id": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"namespace": {
"type": "string",
"minLength": 1
},
"locale": {
"type": "string",
"minLength": 1
},
"missing_count": {
"type": "integer",
"minimum": 1
},
"source_count": {
"type": "integer",
"minimum": 1
},
"missing_keys": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
}
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Missing ar translations in app_topolo_forms",
"body": "2 ar translations are missing.",
"category": "localize",
"severity": "warning",
"object_type": "translation_missing_keys",
"object_id": "localize_missing_123",
"app_id": "app_topolo_forms",
"namespace": "common",
"locale": "ar",
"missing_count": 2,
"source_count": 180,
"missing_keys": [
"forms.export.title",
"forms.export.ready"
],
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^localize:missing-keys:"
},
"sensitiveFields": []
},
{
"type": "localize.review.requested",
"version": 1,
"description": "A platform operator persisted a request to review one translated catalog locale.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"app_id",
"namespace",
"locale",
"message",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"category": {
"const": "localize"
},
"severity": {
"const": "info"
},
"object_type": {
"const": "translation_review"
},
"object_id": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"namespace": {
"type": "string",
"minLength": 1
},
"locale": {
"type": "string",
"minLength": 1
},
"message": {
"type": [
"string",
"null"
]
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Translation review requested for app_topolo_forms",
"body": "Please review the Arabic export workflow copy.",
"category": "localize",
"severity": "info",
"object_type": "translation_review",
"object_id": "localize_review_123",
"app_id": "app_topolo_forms",
"namespace": "common",
"locale": "ar",
"message": "Please review the Arabic export workflow copy.",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^localize:review:"
},
"sensitiveFields": [
"message"
]
},
{
"type": "localize.source.drift_detected",
"version": 1,
"description": "Persisted source strings changed hash and made existing translations candidates for review.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"app_id",
"namespace",
"source_locale",
"changed_count",
"changed_keys",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"category": {
"const": "localize"
},
"severity": {
"const": "warning"
},
"object_type": {
"const": "translation_source_drift"
},
"object_id": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"namespace": {
"type": "string",
"minLength": 1
},
"source_locale": {
"type": "string",
"minLength": 1
},
"changed_count": {
"type": "integer",
"minimum": 1
},
"changed_keys": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1
}
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Source strings changed in app_topolo_forms",
"body": "2 source strings have changed and may need translation review.",
"category": "localize",
"severity": "warning",
"object_type": "translation_source_drift",
"object_id": "localize_drift_123",
"app_id": "app_topolo_forms",
"namespace": "common",
"source_locale": "en",
"changed_count": 2,
"changed_keys": [
"forms.export.title",
"forms.export.ready"
],
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^localize:source-drift:"
},
"sensitiveFields": []
},
{
"type": "localize.translation.completed",
"version": 1,
"description": "A persisted translation generation run reached its successful terminal state.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"app_id",
"namespace",
"target_locale",
"translated_count",
"model",
"provider",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"category": {
"const": "localize"
},
"severity": {
"const": "success"
},
"object_type": {
"const": "translation_run"
},
"object_id": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"namespace": {
"type": "string",
"minLength": 1
},
"target_locale": {
"type": "string",
"minLength": 1
},
"translated_count": {
"type": "integer",
"minimum": 1
},
"model": {
"type": [
"string",
"null"
]
},
"provider": {
"type": [
"string",
"null"
]
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Translation completed for app_topolo_forms",
"body": "12 ar translations were generated.",
"category": "localize",
"severity": "success",
"object_type": "translation_run",
"object_id": "localize_translation_123",
"app_id": "app_topolo_forms",
"namespace": "common",
"target_locale": "ar",
"translated_count": 12,
"model": "translation-v1",
"provider": "nexus",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^localize:translation:"
},
"sensitiveFields": []
},
{
"type": "localize.translation.failed",
"version": 1,
"description": "A persisted translation generation run reached a failed terminal state after the provider rejected or failed the request.",
"status": "published",
"payloadSchema": {
"type": "object",
"required": [
"title",
"body",
"object_id",
"app_id",
"namespace",
"target_locale",
"error",
"occurred_at"
],
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"body": {
"type": "string",
"minLength": 1
},
"category": {
"const": "localize"
},
"severity": {
"const": "critical"
},
"object_type": {
"const": "translation_run"
},
"object_id": {
"type": "string",
"minLength": 1
},
"app_id": {
"type": "string",
"minLength": 1
},
"namespace": {
"type": "string",
"minLength": 1
},
"target_locale": {
"type": "string",
"minLength": 1
},
"error": {
"type": "string",
"minLength": 1
},
"occurred_at": {
"type": "string",
"format": "date-time"
}
},
"additionalProperties": false
},
"examples": [
{
"title": "Translation failed for app_topolo_forms",
"body": "ar translation generation failed: provider unavailable",
"category": "localize",
"severity": "critical",
"object_type": "translation_run",
"object_id": "localize_translation_456",
"app_id": "app_topolo_forms",
"namespace": "common",
"target_locale": "ar",
"error": "provider unavailable",
"occurred_at": "2026-07-20T00:00:00.000Z"
}
],
"dataClassification": "internal",
"recipients": {
"modes": [
"organization_member"
],
"externalAddress": "forbidden"
},
"idempotency": {
"required": true,
"pattern": "^localize:translation:"
},
"sensitiveFields": [
"error"
]
}
]
},
"actions": [
{
"name": "widget.get",
"title": "Get widget summary",
"description": "Read the TopoloOne widget summary for Localize.",
"method": "GET",
"path": "/api/widget",
"permission": "localize:read",
"readOnly": true,
"target": "web",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by Get widget summary.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/widget",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/widget",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "options.list",
"title": "List catalog options",
"description": "Read available services, namespaces, locales, and catalog versions.",
"method": "GET",
"path": "/api/options",
"permission": "localize:read",
"readOnly": true,
"target": "web",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"description": "Response returned by List catalog options.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/options",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/options",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "entries.list",
"title": "List translation entries",
"description": "Read joined source and translation entries for a catalog slice.",
"method": "GET",
"path": "/api/entries",
"permission": "localize:read",
"readOnly": true,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List translation entries.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/entries",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/entries",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sources.list",
"title": "List source strings",
"description": "Read source strings for a service namespace.",
"method": "GET",
"path": "/api/sources",
"permission": "localize:read",
"readOnly": true,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List source strings.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example",
"namespace": "example",
"q": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/sources",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/sources",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "values.list",
"title": "List translated values",
"description": "Read translated values for a service namespace.",
"method": "GET",
"path": "/api/values",
"permission": "localize:read",
"readOnly": true,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by List translated values.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"appId": "example",
"namespace": "example",
"q": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/values",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/values",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sources.upsert",
"title": "Upsert source string",
"description": "Create or update one Localize source string.",
"method": "PUT",
"path": "/api/sources",
"permission": "localize:write",
"readOnly": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Upsert source string.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"key": "example",
"sourceText": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/sources",
"body": {
"appId": "app_topolo_example",
"key": "example",
"sourceText": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/sources",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sources.bulk_upsert",
"title": "Bulk upsert source strings",
"description": "Create or update a batch of Localize source strings.",
"method": "POST",
"path": "/api/sources/bulk",
"permission": "localize:write",
"readOnly": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Bulk upsert source strings.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"sources": {}
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/sources/bulk",
"body": {
"appId": "app_topolo_example",
"sources": {}
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/sources/bulk",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "values.upsert",
"title": "Upsert translated value",
"description": "Create or update one translated value.",
"method": "PUT",
"path": "/api/values",
"permission": "localize:write",
"readOnly": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Upsert translated value.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"key": "example",
"locale": "en-US",
"value": "example"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "PUT",
"path": "/api/values",
"body": {
"appId": "app_topolo_example",
"key": "example",
"locale": "en-US",
"value": "example"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "PUT /api/values",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "values.bulk_upsert",
"title": "Bulk upsert translated values",
"description": "Create or update a batch of translated values.",
"method": "POST",
"path": "/api/values/bulk",
"permission": "localize:write",
"readOnly": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Bulk upsert translated values.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"locale": "en-US",
"values": {}
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/values/bulk",
"body": {
"appId": "app_topolo_example",
"locale": "en-US",
"values": {}
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/values/bulk",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "translations.generate",
"title": "Generate translations",
"description": "Generate translated values for a service namespace.",
"method": "POST",
"path": "/api/translations/generate",
"permission": "localize:write",
"readOnly": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Generate translations.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"targetLocale": "en-US"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/translations/generate",
"body": {
"appId": "app_topolo_example",
"targetLocale": "en-US"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/translations/generate",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "reviews.request",
"title": "Request translation review",
"description": "Request a human review of a translated catalog slice.",
"method": "POST",
"path": "/api/reviews",
"permission": "localize:write",
"readOnly": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Request translation review.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"locale": "en-US"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/reviews",
"body": {
"appId": "app_topolo_example",
"locale": "en-US"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/reviews",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "catalogs.publish",
"title": "Publish catalog",
"description": "Publish a Localize catalog bundle for a service namespace and locale.",
"method": "POST",
"path": "/api/catalogs/publish",
"permission": "localize:publish",
"readOnly": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Publish catalog.",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"locale": "en-US"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/catalogs/publish",
"body": {
"appId": "app_topolo_example",
"locale": "en-US"
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/catalogs/publish",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "sources.prune",
"title": "Prune source strings",
"description": "Remove source strings and orphan values outside a provided key set.",
"method": "POST",
"path": "/api/sources/prune",
"permission": "localize:write",
"readOnly": false,
"destructive": true,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"description": "Response returned by Prune source strings.",
"additionalProperties": true
},
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"keys": [
"example"
]
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/sources/prune",
"body": {
"appId": "app_topolo_example",
"keys": [
"example"
]
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/sources/prune",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "catalogs.index",
"title": "List catalog index",
"description": "List and filter Localize catalog health and publication state.",
"method": "GET",
"path": "/api/catalog-index",
"permission": "localize:read",
"readOnly": true,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"destructive": false,
"requiresConfirmation": false,
"agentAccess": "auto",
"documentation": {
"example_input": {
"q": "example",
"appId": "example",
"locale": "en-US"
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --json"
],
"http_example": {
"method": "GET",
"path": "/api/catalog-index",
"body": null
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "GET /api/catalog-index",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "catalogs.rekey",
"title": "Re-key catalog storage",
"description": "Move current catalog objects onto canonical application ID storage keys.",
"method": "POST",
"path": "/api/admin/rekey",
"permission": "localize:publish",
"readOnly": false,
"destructive": true,
"target": "web",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"dryRun": {
"type": "boolean"
},
"limit": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 300
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"dryRun": true,
"limit": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/rekey",
"body": {
"dryRun": true,
"limit": 1
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/admin/rekey",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "catalogs.sync_from_staging",
"title": "Sync catalogs from staging",
"description": "Promote translated staging catalogs into the current production deployment.",
"method": "POST",
"path": "/api/admin/sync-from-staging",
"permission": "localize:publish",
"readOnly": false,
"destructive": false,
"target": "web",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"maxPacks": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"maxPacks": 1
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/admin/sync-from-staging",
"body": {
"maxPacks": 1
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/admin/sync-from-staging",
"evidence": "Matched to a served route extracted from canonical staging source."
}
},
{
"name": "autofill.enqueue",
"title": "Enqueue catalog autofill",
"description": "Register source strings and enqueue missing translations for a service namespace.",
"method": "POST",
"path": "/api/autofill/enqueue",
"permission": "localize:write",
"readOnly": false,
"destructive": false,
"target": "web",
"inputSchema": {
"$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
},
"outputSchema": {
"type": "object",
"additionalProperties": true
},
"requiresConfirmation": true,
"agentAccess": "confirm",
"documentation": {
"example_input": {
"appId": "app_topolo_example",
"namespace": "example",
"sources": {}
},
"cli_example": [
"topolo actions --service topolo-platform --json",
"topolo actions get <action-id> --json",
"topolo actions validate <action-id> --data @payload.json --json",
"topolo actions plan <action-id> --data @payload.json --json",
"topolo actions call <action-id> --data @payload.json --confirm --json"
],
"http_example": {
"method": "POST",
"path": "/api/autofill/enqueue",
"body": {
"appId": "app_topolo_example",
"namespace": "example",
"sources": {}
}
},
"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."
],
"docs_url": null,
"resource": null,
"next_action_ids": [],
"rollback_action_id": null
},
"implementation": {
"status": "implemented",
"route_key": "POST /api/autofill/enqueue",
"evidence": "Matched to a served route extracted from canonical staging source."
}
}
],
"action_coverage": {
"status": "ok",
"served_routes": 23,
"matched_actions": 17,
"declared_unserved_actions": [],
"coverage_excluded_actions": [],
"uncatalogued_routes": [],
"ignored_routes": 6,
"configured_exclusions": 4,
"configuration_findings": [],
"notes": []
},
"runtime_contract_audit": {
"status": "verified",
"actions": 17,
"contracts": 17,
"contract_module": "topolo.action-contracts.mjs",
"validator_sources": [
"src/index.js"
],
"authorization_sources": [
"src/index.js"
],
"findings": []
}
}
],
"mobile_contracts": [
{
"source_path": "topolo-platform/services/TopoloLocalize/topolo.mobile-experience.json",
"contract": {
"version": "2026-06-29",
"status": "approved",
"mode": "native_capability",
"appId": "app_topolo_localize",
"localizationNamespace": "localize",
"permissions": [
"localize:read"
],
"offlinePolicy": "read_through_cache",
"fallbackPath": "/catalogs",
"auth": {
"audience": "topolo-localize",
"scopes": [
"localize:read"
]
},
"routes": [
{
"path": "/catalogs",
"apiPath": "/api/catalog-index",
"title": "Catalogs",
"titleKey": "localize.mobile.routes.catalogs.title",
"template": "record.list",
"dataSource": "localize.catalogs.list"
}
]
}
}
],
"package_manifests": [],
"deployment_configs": [
{
"source_path": "topolo-platform/core/TopoloCloudControl/staging-activity-worker/wrangler.jsonc",
"name": "topolo-staging-activity",
"main": "src/worker.js",
"compatibility_date": "2026-04-29",
"observability_enabled": true,
"environments": [],
"variable_names": [
"ACTIVITY_MAX_ORGS",
"BURST_DURATION_MINUTES",
"BURST_STARTED_AT",
"BURST_UNTIL",
"BURST_USAGE_LEVEL",
"SEEDED_ORG_COUNT",
"USAGE_LEVEL"
],
"routes": [],
"cron_triggers": [],
"bindings": [
{
"kind": "d1",
"binding": "SEED_DB",
"target": null
},
{
"kind": "d1",
"binding": "SOCIALIZE_BRANDS_DB",
"target": null
},
{
"kind": "d1",
"binding": "SOCIALIZE_CONTENT_DB",
"target": null
},
{
"kind": "d1",
"binding": "SOCIALIZE_INTEGRATIONS_DB",
"target": null
},
{
"kind": "d1",
"binding": "SOCIALIZE_ANALYTICS_DB",
"target": null
},
{
"kind": "d1",
"binding": "LEARN_DELIVERY_DB",
"target": null
},
{
"kind": "d1",
"binding": "LEARN_EVENTS_DB",
"target": null
},
{
"kind": "d1",
"binding": "FEED_DEVICES_DB",
"target": null
},
{
"kind": "d1",
"binding": "FEED_IMPRESSIONS_DB",
"target": null
},
{
"kind": "d1",
"binding": "CAPACITY_DB",
"target": null
}
]
}
],
"source_signals": {
"api_routes": [
{
"method": "ALL",
"path": "*",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "OPTIONS",
"path": "*",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "ALL",
"path": "/__seed/*",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/internal/platform/encryption/master-key/rewrap",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/service-api-key-resources/sync",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/orgs/:orgId/sync-base-seat-count",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/app-permissions",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/app-registration",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/internal/entitlements",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/entitlements",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/organizations/:orgId/app-entitlement",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/reconcile/app-entitlements",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/provision-from-checkout",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/internal/organizations/slug-availability",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/users/:userId/permissions",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/users/:userId/service-permissions",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/users/:userId/service-permissions",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "DELETE",
"path": "/api/users/:userId/service-permissions/:overrideId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/users/:userId/service-access",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/users/:userId/service-access",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/organization-services",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/organization-services/:relationshipId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/organization-services",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/organization-services/:relationshipId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "DELETE",
"path": "/api/organization-services/:relationshipId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/organization-services/check/:organizationId/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/organizations/:orgId/services",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/me/services",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/app-switcher/preferences",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/app-switcher/preferences/events",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/app-switcher/preferences",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/i18n/preferences",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/i18n/preferences",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/machine/registry",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/machine/handoffs",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/services/:appId/organizations",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/api-keys",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/api-keys/options",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/api-keys",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/api-keys/:apiKeyId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/api-keys/:apiKeyId/revoke",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/api-keys/introspect",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/auth/me",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/login-config/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/login-config/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/login-config-master",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/login-config-master",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/landing-config/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/landing-config/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/admin/platform-pricing",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/admin/platform-pricing",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/admin/pricing-plans/by-app/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/admin/pricing-plans/bulk-register",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/admin/billing/register-app-pricing",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/app-ui-config/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/app-ui-config/:appId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/login-events",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/login-events",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/login-events/:eventId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "DELETE",
"path": "/api/login-events/:eventId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/login-presets",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/login-presets",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "DELETE",
"path": "/api/login-presets/:presetId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/login",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/signup",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/tokens/revoke",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/revoke",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/oauth/token",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/register",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/public/organizations",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/public/validate-invite",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/invitations",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/invitations",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "DELETE",
"path": "/api/invitations/:invitationId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/resource-grants/me",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/resource-grants",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/resource-grants/:grantId/revoke",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/resource-grants/promote",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/workspaces",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/workspaces",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PATCH",
"path": "/api/workspaces/:workspaceId",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "PUT",
"path": "/api/workspaces/:workspaceId/default",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/internal/workspaces/default",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/workspaces/:workspaceId/archive",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/internal/workspaces/resolve-provisioning",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/workspace-access/me",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/api/workspace-access/:resourceId/members",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/workspace-access/:resourceId/members",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/workspace-access/:resourceId/members/revoke",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/api/workspace-access/:resourceId/transfer",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "GET",
"path": "/health",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "POST",
"path": "/cleanup",
"source_path": "topolo-platform/core/TopoloAuth/src/index.js"
},
{
"method": "ALL",
"path": "*",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/health",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/api/health",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/api/app-identity",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/auth/callback",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/internal",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/api/bootstrap",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/api/widget",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/api/docs",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/api/docs/platform-corpus/sync",
"source_path": "system-apps/TopoloDocs/apps/api/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/",
"source_path": "system-apps/TopoloDocs/apps/web/src/worker.ts"
},
{
"method": "LITERAL",
"path": "/health",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/app-identity",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/catalog-manifest",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/catalog-versions",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/widget",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/admin/sync-from-staging",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/catalog-index",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/options",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/entries",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/sources",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/sources/bulk",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/sources/prune",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/values",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/values/bulk",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/catalogs/publish",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/reviews",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/admin/rekey",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/translations/generate",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
},
{
"method": "LITERAL",
"path": "/api/autofill/enqueue",
"source_path": "topolo-platform/services/TopoloLocalize/src/index.js"
}
],
"ui_routes": [
{
"path": "/",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/dashboard",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/deployments",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/projects",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/projects/:id",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/branches",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/cloudflare",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/local-dev",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/infrastructure",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/api-keys",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/secrets",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/actions",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/settings",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/account",
"source_path": "topolo-platform/core/TopoloCloudControl/src/App.tsx"
},
{
"path": "/app",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/spaces",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/spaces/:spaceId",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/read/:spaceId",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/read/:spaceId/:documentId",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/documents/:documentId",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/documents/:documentId/edit",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/search",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/app/settings",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/s/:spaceSlug/:documentSlug?",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
},
{
"path": "/reference/actions",
"source_path": "system-apps/TopoloDocs/apps/web/src/App.tsx"
}
],
"test_cases": [],
"database_tables": []
},
"documentation": {
"declared_paths": [
"platform/deep-dive",
"platform/architecture",
"platform/api-keys",
"internal/platform/identity-access-entitlements",
"internal/platform/auth-and-identity",
"internal/platform/ai-workforce-credentials",
"internal/platform/security-assurance",
"internal/platform/production-readiness-evaluation",
"internal/platform/isolated-installations",
"internal/platform/platform-inventory",
"internal/platform/repo-structure",
"internal/platform/deploy-pipeline",
"internal/platform/application-build-contract",
"internal/platform/api-key-resource-bindings",
"internal/platform/design-language",
"internal/platform/ui-translations",
"internal/apps/topolo-localize",
"internal/platform/topolo-ui-kit",
"internal/platform/mobile-experience-rollout",
"internal/platform/data-privacy-and-encryption",
"internal/platform/shared-packages"
],
"present_paths": [
"platform/deep-dive",
"platform/architecture",
"platform/api-keys",
"internal/platform/identity-access-entitlements",
"internal/platform/auth-and-identity",
"internal/platform/ai-workforce-credentials",
"internal/platform/security-assurance",
"internal/platform/production-readiness-evaluation",
"internal/platform/isolated-installations",
"internal/platform/platform-inventory",
"internal/platform/repo-structure",
"internal/platform/deploy-pipeline",
"internal/platform/application-build-contract",
"internal/platform/api-key-resource-bindings",
"internal/platform/design-language",
"internal/platform/ui-translations",
"internal/apps/topolo-localize",
"internal/platform/topolo-ui-kit",
"internal/platform/mobile-experience-rollout",
"internal/platform/data-privacy-and-encryption",
"internal/platform/shared-packages"
],
"missing_paths": [],
"human_reference": "/systems/topolo-platform",
"machine_reference": "/machine/systems/topolo-platform.json",
"action_examples": 232,
"action_schemas": 232
},
"source_findings": [
{
"type": "uncatalogued_routes",
"source_path": "topolo-platform/core/TopoloAuth/topolo.app.json",
"detail": [
{
"key": "GET /favicon.svg",
"method": "GET",
"path": "/favicon.svg",
"source": "src/auth-core-routes.js",
"target": "api"
},
{
"key": "POST /api/surface-launches",
"method": "POST",
"path": "/api/surface-launches",
"source": "src/auth-core-routes.js",
"target": "api"
},
{
"key": "POST /api/surface-sessions",
"method": "POST",
"path": "/api/surface-sessions",
"source": "src/auth-core-routes.js",
"target": "api"
},
{
"key": "POST /internal/platform/encryption/master-key/rewrap",
"method": "POST",
"path": "/internal/platform/encryption/master-key/rewrap",
"source": "src/index.js",
"target": "api"
}
]
}
]
}